ATTACH

ATTACH

Create a New Subtask

Portability: SAS/C extension

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTIONS
IMPLEMENTATION
EXAMPLE
RELATED FUNCTIONS

SYNOPSIS

#include <ostask.h>

int ATTACH(void **tcbaddr, ...);

DESCRIPTION

The ATTACH function implements the functionality of the OS/390 assembler ATTACH macro. The tcbaddr argument is the address of a void * area where the address of the new task control block (TCB) is to be stored. The remainder of the argument list is a list of keywords followed, in most cases, by an argument specifying a value for the keyword. The list is terminated by the _Aend keyword.

The supported keywords and their associated data are as follows:

The _Aep keyword is equivalent to the Assembler EP keyword. The next argument should be a null-terminated string containing the name of the load module to attach. The name is translated to uppercase and padded to eight characters.
The _Adcb keyword is equivalent to the Assembler DCB keyword. The next argument should be a pointer to an open DCB. (A DSORG=PO DCB obtained using the osdcb and osbopen functions may be used.)
The _Alpmod keyword is equivalent to the Assembler LPMOD keyword. The next argument should be an unsigned char value to be subtracted from the limit priority of the new task.
The _Adpmod keyword is equivalent to the Assembler DPMOD keyword. The next argument should be a signed integer value to be added to the dispatching priority of the new task.
The _Aparam keyword is equivalent to the Assembler PARAM keyword. The next argument should be a pointer to a list of arguments to be passed to the new task. (This value is loaded into register 1 before the new task is attached.) If no parameter list is specified, a value of 0 is placed in register 1 before the ATTACH function is called. Many programs do not tolerate a 0 parameter pointer, and if you are not certain of the parameter list requirements of the program you are attaching, a parameter list containing a pointer to a halfword of zeroes is recommended. If you are attaching a SAS/C program, you should not pass a 0 parameter pointer. (See "Calling a C Program from Assembler" in Chapter 11 of the SAS/C Compiler and Library User's Guide, Third Edition, for more information on passing parameters to SAS/C load modules.)
The _Aecb keyword is equivalent to the Assembler ECB keyword. The next argument should be a pointer to a fullword, which is an ECB to be posted by the POST macro when the subtask terminates.
The _Aetxr keyword is equivalent to the Assembler ETXR keyword. The next argument should be a __remote function pointer that specifies the address of a C function to be called when the subtask terminates. Linkage for this function is as follows:
```
void etxr(void *tcbaddr);
```
The function argument is the address of the terminated TCB. The ETXR routine receives control in SPE as a bldexit routine. In the full library implementation the ETXR routine can receive control anytime an asynchronous signal handler could receive control.
The _Ashspl keyword is equivalent to the Assembler SHSPL keyword. The next argument should be a char * , pointing to a list of subpool numbers preceded by the number of subpools in the list. Subpool 78 is always shared with subtasks created by the SAS/C ATTACH function, whether explicitly specified or not.
The _Aszerono keyword is equivalent to the Assembler keyword SZERO=NO. This keyword does not take a value. The next argument should be another keyword.
The _Atasklib keyword is equivalent to the Assembler TASKLIB keyword. The next argument should be a pointer to an open DCB. (A DSORG=PO DCB obtained using the osdcb and osbopen functions may be used.)
The _Aend keyword indicates the end of the list of keywords.

The following should be noted about subtask termination. If neither an _Aecb nor _Aetxr keyword was specified, the subtask TCB is automatically detached when it terminates. Otherwise, the program is required to detach the TCB itself after the subtask has terminated. (Refer to the DETACH macro later in this chapter.)

If a C program terminates normally with active subtasks created by the ATTACH function, the library detaches these subtasks automatically. If a subtask has terminated, the library assumes that the program has detached it. If this assumption is untrue, the program will be abnormally terminated by the operating system.

If an active subtask is detached by the program using the C DETACH macro, an ETXR routine is not called. Also, ETXR routines are not called for tasks detached by the library during normal program termination.

RETURN VALUE

ATTACH returns 0 if the ATTACH macro was successful. If the ATTACH macro fails, it returns the return code from the macro, which will be a positive value. ATTACH may also return -1 to indicate an unknown keyword, or -2 if there was not enough memory to do the attach.

CAUTIONS

In general, the _Aparam keyword should always be specified. See the discussion of this keyword under "DESCRIPTION."

You should be wary of defining subtask parameters in automatic storage, unless the calling function waits for the subtask to complete. Otherwise, the storage for the parameters could be freed or reused while the subtask is accessing them.

IMPLEMENTATION

The ATTACH function is implemented by the source module L$UATTA. The SPE implementation of ETXR exits is provided by the source module L$UAEOT.

EXAMPLE

This example attaches the SAS/C Compiler out of the DDname SASCLIB, and uses the WAIT1 function to wait for it to complete.

#include <ostask.h>
#include <stdio.h>
#include <osio.h>

DCB_t *tasklib;
unsigned myecb;
int rc;
void *subtcb;
void *plist [1]  ;                     /* parm list for compiler     */
struct {
   short len;
   char options[8];
} argument = {8, "OPTIMIZE"};

tasklib = osdcb("SASCLIB", "DSORG=PO", NULL, 0);
if (!tasklib) abort();
if (osbopen(tasklib, "input")) abort();
myecb = 0;                           /* Initialize ECB.            */
plist [  0]   = (void *)(0x80000000 | (unsigned) &  argument);
   /* Set up compiler parm list.                                   */
rc = ATTACH(&subtcb, _Aep, "LC370B", _Atasklib, tasklib, _Aecb,
            &myecb, _Aparam, plist, _Aend);
if (rc != 0) abort();             /* if the ATTACH failed          */
WAIT1(&  myecb);                  /* Wait for compiler to complete.*/
DETACH(&  subtcb,NOSTAE);         /* Detach the TCB.               */
printf("Compiler return code %d\n",
        /* Display compiler return code.                           */
        myecb &   0x3fffffff);
osbclose(tasklib, "disp", 1);

RELATED FUNCTIONS

DETACH , oslink , system

Chapter Contents
Previous
Next
Top of Page