MVS Multitasking and Other Low-Level System Interfaces

Introduction

SAS/C Software provides a number of C macros and functions that allow you to issue common MVS and CMS system macros without having to code any assembler language. Interfaces are provided supporting low-level memory allocation, terminal I/O, and multitasking (MVS only). Most of these macros and functions can be used with either the standard SAS/C Library or with the Systems Programming Environment (SPE). In a few cases, macros can be used only with SPE, due to the existence of conflicting functionality in the standard SAS/C Library. (For instance, the STIMER macro conflicts with the standard alarm function.) Declarations for the SPE-only functions are collected in the header file <spetask.h>.

These interfaces provide little functionality beyond that available using standard system assembler macros like ATTACH and DETACH. Their purpose is the convenience of avoiding assembler interface routines rather than functional enhancements. The syntactic form of the SAS/C low-level macros and functions has been defined to be as similar as possible to the assembler macros, which facilitates the use of the assembler documentation. (See IBM's MVS/ESA Application Development Reference: Services for Assembler Language Programs and VM/ESA CMS Application Development Reference for Assembler.)

Multitasking SAS/C Applications

Note that when you run multiple SAS/C tasks in an address space, each task must have its own C framework. That is, each subtask load module must include a main function, or must use the indep compiler option to create a new C framework. Each SAS/C framework in an address space operates completely independently of the others. This means that you can use objects created by the library only under the task by which they were created. Specifically:

You cannot allocate storage with malloc or palloc in one framework and free it with free or pfree in another.
You cannot dynamically load a SAS/C load module in one framework and call it or unload it in another.
You cannot open a C file (using either UNIX-style or standard I/O) in one framework and use it in another.
Depending on the application, it may be necessary to redirect standard files for SAS/C subtasks. If the standard files are allocated to the terminal or to MVS SYSOUT, generally no problems will result from using them from all subtasks; but if stdout or stderr is a disk file, lost output and or I/O errors may occur.
Each framework has its own defined run-time options. Run-time options are not automatically inherited, and must be set explicitly (either by the caller or by use of _options in the subtask) if the defaults are not suitable.
It is possible, in most situations, to run the SAS/C Debugger in several tasks at the same time. However, this is not recommended. A separate invocation of the debugger is needed for each task, which significantly increases total memory requirements. In addition, it is often difficult to control which debugger will receive input commands. (For this reason, running the debugger in line mode in this situation is recommended.)
Only external and permanent scope environment variables are shared between frameworks.
OpenEdition resources such as file descriptors and signal handlers are shared between all tasks in an address space. For this reason, it is recommended that no more than one task in an address space use OpenEdition functionality.

Note: Many of these restrictions can be bypassed by using operating system facilities directly. For instance, memory allocated by GETMAIN and DCBs processed using BSAM I/O can be shared freely among subtasks so long as all MVS restrictions are honored.

Compatibility Changes

With Release 5.50, some of the symbols defined in the <tput.h> and <bldexit.h> header files have been changed. To avoid conflicts with <ostask.h> or <spetask.h>, you must replace some of the symbols that were defined in prior releases of the SAS/C Compiler.

The changes shown in Table 4.1 apply to the TPUT and TGET macros defined in <tput.h>.

Table 4.1: <tput.h> Changes

   Old Form   New Form

   EDIT        _EDIT

   ASIS        _ASIS

   CONTROL     _CONTROL

   FULLSCR     _FULLSCR

   WAIT        _WAIT

   NOWAIT      _NOWAIT

   HOLD        _HOLD

   NOHOLD      _NOHOLD

   BREAKIN     _BREAKIN

   NOBREAK     _NOBREAK

   HIGHP       _HIGHP

   LOWP        _LOWP

The changes shown in Table 4.2 apply to the bldexit function defined in <bldexit.h>.

Table 4.2: <bldexit.h> Changes

   Old Form   New Form

   ASYNCH      _ASYNCH

   NOR13       _NOR13

   FLOATSV     _FLOATSV

   AMODE       _AMODE

Function Descriptions

Descriptions of the low-level multitasking functions follow. Each description includes a synopsis, description, discussion of return values and portability issues, and an example. Also errors, cautions, diagnostics, implementation details, and usage notes are included where appropriate.

ABEND -- Abnormally Terminate a Program

SYNOPSIS

 #include <spetask.h>

 void ABEND(unsigned code, unsigned reason, dumpopt, sysopt);

DESCRIPTION

The SAS/C ABEND macro implements the functionality of the MVS Assembler ABEND macro. The code argument specifies the ABEND code, and the reason argument specifies the reason code. dumpopt may be specified as either DUMP or NODUMP, to indicate whether a dump should be produced. sysopt may be specified as either USER or SYSTEM to indicate whether the ABEND is a system ABEND or a user ABEND.

CAUTIONS

ABEND is intended for use only in the SPE environment. The library functions abort or abend should be used to force abnormal termination when using the full library.

EXAMPLE

This example terminates the application with system ABEND code BAD and reason code 0.

 #include <spetask.h>

 ABEND(0xbad,0,DUMP,SYSTEM);

RELATED FUNCTIONS

abend, abort

ATTACH -- Create a New Subtask

SYNOPSIS

 #include <ostask.h>

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

DESCRIPTION

The ATTACH function implements the functionality of the MVS 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

CHAP -- Change a Task's Priority

SYNOPSIS

 #include <ostask.h>

 void CHAP(int prio, void **tcbaddr);

DESCRIPTION

The SAS/C CHAP macro implements the functionality of the MVS Assembler CHAP macro. The prio argument is the amount by which the priority of the specified task should be changed. The tcbaddr argument is the address of a fullword containing the address of the TCB whose priority is to be changed or 0 if the priority of the active task is to be changed.

CMSSTOR -- Allocate or Free Storage

SYNOPSIS

 #include <cmsstor.h>

 int CMSSTOR_OBT(unsigned int bytes, void **loc, char *subpool,
                 char options , int erresp);

 int CMSSTOR_REL(unsigned int bytes, void *loc2, char *subpool,
                 char options , int erresp);

DESCRIPTION

These functions simulate the CMSSTOR macro. CMSSTOR_OBT requests a fixed amount of free storage. CMSSTOR_REL releases free storage that has been allocated by CMSSTOR_OBT.

Each macro causes the compiler to generate an SVC 204, with register 1 addressing an appropriate parameter list. Most of the arguments correspond directly to the equivalent assembler macro parameters.

bytes

is the number of bytes of free storage to be allocated by CMSSTOR_OBT or released by CMSSTOR_REL.

loc

is a pointer to a void * where the address of the first byte of allocated storage can be stored.

loc2

is a pointer to the storage to be freed.

subpool

is a pointer to a null-terminated string containing the name of the CMS subpool from which storage is to be allocated or freed. If the subpool is specified as a null string, storage is allocated from the subpool "CMS" or released from the subpool in which it was allocated. The subpool must be a PRIVATE or SHARED subpool, not a GLOBAL subpool.

options

is a set of option flags. Option flags are defined as macros in <cmsstor.h>. There are three types of option flags, corresponding to the assembler macro keyword parameters MSG, LOC, and BNDRY.

MSG options: indicate whether or not a message is to be issued if a failure occurs. There are two MSG flags: MSG_YES and MSG_NO.
LOC options: specify the location of the storage requested. There are four LOC flags: LOC_ABOVE specifies storage above the 16-megabyte line, LOC_BELOW specifies storage below the 16-megabyte line, LOC_SAME specifies storage located according to the addressing mode of the calling program, and LOC_ANY specifies any location.
BNDRY options: specify the required alignment for the requested storage. There are two BNDRY flags: BNDRY_DWORD requests doubleword alignment, and BNDRY_PAGE requests page alignment.

Also, the macros OBT_DEF and REL_DEF are defined. These macros represent the defaults used by the CMSSTOR assembler macro when the MSG, LOC, and BNDRY parameters are omitted. They are defined as

 MSG_YES+LOC_SAME+BNDRY_DWORD

erresp

indicates how a failure is to be handled. Two macros are defined in <cmsstor.h>. Use the macro ERR_RET to indicate that a nonzero value is to be returned in the event of a failure. Use the macro ERR_ABN to indicate that the system should abend in the event of a failure.

RETURN VALUE

Each macro returns the value in register 15 after the SVC 204 has completed. For CMSSTOR_OBT, the value in register 1 is stored in the void * pointed to by loc.

ERRORS AND DIAGNOSTICS

The possible errors are the same as when the CMSSTOR Assembler macro is used in an assembler language program.

CAUTION

The macros do not perform any error checking on their arguments. Incorrect arguments such as invalid combinations of option flags are either ignored entirely or remain undetected until execution time, at which point they cause unpredictable and probably undesirable results.

PORTABILITY

None of the macros are portable.

DEQ -- Release an Enqueued Resource

SYNOPSIS

 #include <ostask.h>

 int DEQ(char *qname, char *rname, int rlen, scope, ret);

DESCRIPTION

The SAS/C DEQ macro implements the functionality of the MVS Assembler DEQ macro. The qname argument specifies the queue name and must be eight or more characters in length; only the first eight characters are used. The rname argument specifies the resource name. Both qname and rname are passed to the DEQ SVC as is. The library does not pad or translate the strings in any way.

The rlen argument specifies the length of the rname. The scope argument specifies whether the scope of the name is the job step, the current system, or all systems in a complex. scope must be specified as one of the keywords STEP, SYSTEM, or SYSTEMS. The ret argument specifies the same information as the assembler RET keyword and must be either NONE or HAVE.

RETURN VALUE

The SAS/C DEQ macro returns the same value as the return code from the assembler DEQ macro.

EXAMPLE

See the example for ENQ.

RELATED FUNCTIONS

ENQ

DETACH -- Remove a Subtask from the System

SYNOPSIS

 #include <ostask.h>

 int DETACH(void **tcbaddr, option);

DESCRIPTION

The SAS/C DETACH macro implements the functionality of the MVS Assembler DETACH macro. The tcbaddr argument is the address of a void * area containing the address of the TCB to be detached. The option argument must be specified as either STAE or NOSTAE, indicating whether the assembler STAE=YES or STAE=NO option is required.

DETACH must be used for a terminated subtask to remove the TCB from the system. If any subtasks created by the SAS/C ATTACH function are still running when the program terminates, these subtasks are detached automatically.

RETURN VALUE

The DETACH macro returns the value returned in register 15 by the assembler DETACH macro.

EXAMPLE

See the example for the ATTACH macro earlier in this chapter.

RELATED FUNCTIONS

ATTACH

DMSFREE -- Allocate or Free DMSFREE Storage

SYNOPSIS

 #include <dmsfree.h>

 int DMSFREE(unsigned int dwords, void **loc, char options,
             int erresp);

 int DMSFREE_V(unsigned int dwords, unsigned int min,
               void **loc, unsigned int *got, char options,
               int erresp);

 int DMSFRET(unsigned int dwords, void *loc2, char msg,
             int erresp);

DESCRIPTION

These functions simulate the CMS DMSFREE and DMSFRET Assembler macros. DMSFREE requests a fixed amount of free storage. DMSFREE_V requests a variable amount of free storage. DMSFRET releases free storage that has been allocated by DMSFREE or DMSFREE_V.

Each macro causes the compiler to generate an SVC 203, followed by the halfword of flags specified by the macro arguments. Most of the arguments correspond directly to the equivalent assembler macro parameters.

dwords

is the number of doublewords of free storage to be allocated by DMSFREE or DMSFREE_V or released by DMSFRET.

min

is the minimum number of doublewords of free storage to be allocated in a variable request.

loc

is a pointer to a void * where the address of the first byte of allocated free storage can be stored.

loc2

is a pointer to the storage to be freed.

got

is a pointer to an unsigned int where the number of doublewords actually allocated by a variable request can be stored.

options

is a set of option flags. Option flags are defined as macros in <dmsfree.h>. There are three types of option flags, corresponding to the assembler macro keyword parameters TYPE, AREA, and MSG.

TYPE options: specify the type of storage requested. There are two TYPE flags: TYPE_NUC specifies NUCLEUS free storage, and TYPE_USER specifies USER free storage.
AREA options: specify the area of storage from which the request will be filled. There are three AREA flags: AREA_LOW specifies that the request be filled from free storage below the user areas, AREA_HIGH specifies that the request be filled from free storage above the user area, and AREA_ANY specifies that any area can be used.
MSG options: indicate whether or not a message is to be issued if a failure occurs. There are two MSG flags: MSG_YES and MSG_NO.

Also, the macro FREE_DEF is defined. This macro represents the defaults used by the DMSFREE assembler macro when the TYPE, AREA, and MSG parameters are omitted. FREE_DEF is defined as follows:

 AREA_ANY+MSG_YES

Use the FREE_DEF macro as the options argument, or create it by using OR to select one choice from each of the AREA, MSG, and (optionally) TYPE flags. It is not possible to allow the AREA or MSG flag to default.

msg: is one of the two MSG flags.
erresp: indicates how a failure is to be handled. Two macros are defined in <dmsfree.h>. Use the macro ERR_RET to indicate that a nonzero value is to be returned in the event of a failure. Use the macro ERR_ABN to indicate that the system should abend in the event of a failure.

RETURN VALUE

Each macro returns the value in register 15 after the SVC 203 has completed. For DMSFREE and DMSFREE_V, the value in register 1 is stored in the
void * pointed to by loc. For DMSFREE_V, the value in register 0 is stored in the unsigned int pointed to by got.

ERRORS AND DIAGNOSTICS

The possible errors are the same as when the DMSFREE or DMSFRET assembler macros are used in an assembly language program.

CAUTION

PORTABILITY

None of the macros are portable.

ENQ -- Wait for a Resource to Become Available

SYNOPSIS

 #include <ostask.h>

 int ENQ(char *qname, char *rname, excl, int rlen, scope, ret);

DESCRIPTION

The SAS/C ENQ macro implements the functionality of the MVS Assembler ENQ macro. The qname argument specifies the queue name and resource name and must be eight or more characters in length; only the first eight characters are used. The rname argument specifies the resource name. Both the qname and rname are passed to the ENQ SVC as is; that is, the library does not pad or translate the strings in any way.

The excl argument specifies whether this is an exclusive or shared request and must be specified as either E or S. The rlen argument specifies the length of rname. The scope argument specifies whether the scope of the name is the job step, the current system, or all systems in a complex. It must be specified as one of the keywords STEP, SYSTEM, or SYSTEMS. The ret argument specifies the same information as the assembler RET keyword and must be NONE, HAVE, CHNG, USE or TEST.

RETURN VALUE

The SAS/C ENQ macro returns the same value as the return code from the assembler ENQ macro.

EXAMPLE

Use the ENQ function to obtain shared control of the resource with qname MYQN and rname FRED.ACCTS.DATA. RET=HAVE is used to prevent ABEND if the resource is unavailable.

 static char rname [] = "FRED.ACCTS.DATA";
 int rc;

 rc = ENQ("MYQN    ", rname, S, sizeof(rname)-1, SYSTEM, HAVE);
 if (rc != 0)
    printf("ENQ failed!\n");
 else {
    process();     /* utilize the resource */
    DEQ("MYQN    ", rname, sizeof(rname)-1, SYSTEM, NONE);
 }

RELATED FUNCTIONS

DEQ

ESTAE -- Define an Abnormal Termination Exit

SYNOPSIS

 #include <spetask.h>

 int ESTAE(void *exit, create, void *param, asynch, term);

 int ESTAE_CANCEL(void);

DESCRIPTION

The SAS/C ESTAE and ESTAE_CANCEL macros implement the functionality of the MVS assembler ESTAE macro. This macro is supported only with the Systems Programming Environment (SPE).

The exit argument of ESTAE is the address of code to receive control if the program ABENDs. This argument should ordinarily be specified as a call to the bldexit function, whose first argument is the address of the C function that is to be defined as the exit.

create: must be either CT or OV. Specify CT if a new ESTAE exit is to be defined, or OV if the previous exit is to be overlaid.
param: specifies a pointer that is to be made available to the ESTAE exit when it is called.
asynch: must be specified as ASYNCH or NOASYNCH, to indicate whether or not asynchronous interrupts are allowed in the exit.
term: must be specified as TERM or NOTERM. Indicates whether the exit is to be given control for no-retry terminations such as operator cancel.

The ESTAE_CANCEL macro has the same effect as the assembler ESTAE macro with an exit address of 0. That is, it cancels the most recently defined ESTAE exit.

RETURN VALUE

The ESTAE and ESTAE_CANCEL macros return the ESTAE assembler macro return code in register 15.

CAUTIONS

Use of the ESTAE macro in code that uses the full run-time library interferes with library ABEND handling. Additionally, the bldexit function cannot be used with the full run-time library.

Similar functionality to ESTAE can be obtained with the full library by defining signal handlers for SIGABRT or SIGABND.

EXAMPLE

This example sets up an ESTAE exit and uses SETRP macros within the exit to perform a retry.

 #include <spetask.h>
 #include <bldexit.h>
 #include <setjmp.h>

 jmp_buf retrybuf;
 int rc;

 static void estaeex();
 extern void msgwtr();             /* message-writing subroutine   */

 if (setjmp(retrybuf)) goto retrying;
     /* Set up jump buffer for retry.                              */

 rc = ESTAE(bldexit(&estaeex, ASYNCH+NOR13), CT, 0, NOASYNCH, NOTERM);
 if (rc != 0) {
    msgwtr("ESTAE macro failed!");
    ABEND(1066, rc, DUMP, USER);       /* Give up after failure.   */
 }
 .
 .
 .
 retrying:                             /* Retry code here.         */
 .
 .
 .

 static void estaeex(void **sa, char **poi) {
    void *SDWA;

    if ((int) sa[2]  == 12)            /* Check R0 for 12.         */
       return;                         /* Give up if no memory.    */
    SDWA = sa[3];                      /* Find the SDWA.           */
    SETRP_DUMP(SDWA, YES);             /* Take dump before retry.  */
       /* request a retry at label retrying above                  */
    SETRP_RETRY(bldretry(retrybuf, 1), NOFRESDWA);
    return;
 }

RELATED FUNCTIONS

bldexit, SETRP, signal

GETMAIN/FREEMAIN -- Allocate or Free Virtual Storage

SYNOPSIS

 #include <getmain.h>

 int GETMAIN_C(unsigned int length, int subpool, int options ,
               void **loc);

 int GETMAIN_U(unsigned int length, int subpool, int options );

 int GETMAIN_V(unsigned int max, unsigned int min, int subpool,
               int options , void **loc, unsigned int *alloc);

 int FREEMAIN( void **loc, unsigned int length, int subpool,
               int options );

DESCRIPTION

These functions simulate the use of the MVS GETMAIN and FREEMAIN Assembler macros. GETMAIN_C and GETMAIN_U are used to generate conditional and unconditional requests, respectively, to allocate virtual storage. GETMAIN_V generates a variable request. FREEMAIN generates a request to free virtual storage that has been allocated by one of the GETMAIN_ macros.

Each macro causes the compiler to generate code to load the appropriate values into registers 0, 1, and 15, and then to generate SVC 120 (under MVS) or SVC 10 (under CMS). The use of each argument is explained here.

length: is the number of bytes of virtual storage to be allocated by the GETMAIN_ macros or released by FREEMAIN.
subpool: specifies the number of the subpool from which the storage is to be allocated.
options: is a set of option flags. All option flags are defined as macros in <getmain.h>.
For GETMAIN_U and GETMAIN_C, options is the logical sum of zero or more of the values defined by the macros BNDRY_PAGE, LOC_BELOW, LOC_ANY, and LOC_RES. These options are equivalent to the BNDRY and LOC keyword parameters to the GETMAIN assembler macro. For GETMAIN_V, options also can include COND, indicating a conditional request, or UNCOND, indicating an unconditional request. For FREEMAIN, options can be either COND or UNCOND.
loc: is a pointer to a void * where the address of the allocated storage area can be stored.
max,min: is the maximum and minimum length of the variable request.
alloc: is a pointer to an unsigned int where the length allocated for a variable request can be stored.

RETURN VALUE

GETMAIN_U returns the address of the allocated storage. GETMAIN_V, GETMAIN_C, and FREEMAIN return the value in register 15 after the SVC completes. In addition, GETMAIN_C and GETMAIN_V store the value in register 1 (the address of the allocated storage) in the void * pointed to by loc. GETMAIN_V also stores the value in register 0 (the amount of virtual storage allocated) in the unsigned int addressed by alloc.

ERRORS AND DIAGNOSTICS

The possible errors are the same as if the GETMAIN or FREEMAIN assembler macros are used in an assembly language program.

CAUTIONS

The macros do not perform any error checking on their arguments. Incorrect arguments, such as invalid combinations of option flags, are either ignored entirely or remain undetected until execution time, at which point they cause unpredictable and probably undesirable results.

The compiler generates different code sequences depending on the host operating system. If the program is to be executed on a system other than that under which it is compiled, #define (or #undef) can be used for the symbol CMS name before including <getmain.h>.

PORTABILITY

None of the macros are portable.

IMPLEMENTATION

If the macro name CMS is defined, then CMS versions of the GETMAIN_U and FREEMAIN macros are defined. These versions generate an inline SVC 10. All option flags are ignored. The GETMAIN_C and GETMAIN_V macros are not defined.

If the macro name CMS is not defined, all four macros are defined. The macros generate an inline SVC 120.

EXAMPLE

    /* Allocate a number of pages of 4K-aligned storage. */
 void *pgalloc(int pages, int sp)
 {
    return GETMAIN_U((pages*4096),sp,BNDRY_PAGE+LOC_ANY);
 }

POST -- Post an ECB

SYNOPSIS

 #include <ostask.h>

 void POST(unsigned *ecbaddr, unsigned code);

DESCRIPTION

The SAS/C POST macro implements the functionality of the MVS assembler POST macro. The ecbaddr argument is the address of the ECB to be POSTed. The code argument is the value to be stored in the ECB. The two high-order bits of code are ignored.

RELATED FUNCTIONS

WAIT

RDTERM -- Simulate the RDTERM Assembler Language Macro

SYNOPSIS

 #include <wrterm.h>

 int RDTERM(char *inbuf, short inbufsz, int *inlen);

DESCRIPTION

RDTERM simulates the RDTERM assembler language macro. The RDTERM macro invokes the waitrd macro to produce a parameter list that is equivalent to using the RDTERM assembly language macro with all parameters allowed to default. If the symbol BIMODAL is defined, RDTERM generates an equivalent to the CMS LINERD macro and, therefore, can be used in 31-bit addressing mode.

RETURN VALUE

RDTERM returns the value in register 15 when the WAITRD or LINERD function returns.

ERRORS AND DIAGNOSTICS

The possible errors are the same as when the RDTERM or LINERD macro is used in an assembler language program.

PORTABILITY

RDTERM is not portable.

IMPLEMENTATION

The definition of RDTERM if BIMODAL is not defined is as follows:

 #define RDTERM(b,l,rl) waitrd(b,l,STACK_MIXED,PROMPT_NO,0,0,rl)

EXAMPLE

 char *line[130]
 int len, rc;
    /* Read up to 130 characters with no prompt and no editing. */
 rc = RDTERM(line,sizeof(line),&len);

SETRP -- Set Recovery Parameters in an ESTAE Exit

SYNOPSIS

 #include <spetask.h>

 void SETRP_DUMP(void *sdwa, dumpopt);

 void SETRP_COMPCOD(void *sdwa, unsigned code, sysopt);

 void SETRP_REASON(void *sdwa, unsigned reason);

 void SETRP_RETRY(void *sdwa, void *retry, fresdwa);

DESCRIPTION

The SAS/C SETRP macros implement the most frequently used functions of the MVS Assembler SETRP macro. These macros should be used only in an ESTAE exit. Each macro's first argument is a pointer to the SDWA (System Diagnostic Work Area), which is passed to the exit by the operating system.

SETRP_DUMP overrides the DUMP specification of the original ABEND. dumpopt must be specified as YES or NO to indicate whether or not a dump should be taken.

SETRP_COMPCOD overrides the completion code of the original ABEND. The code argument is the new completion code. The sysopt argument must be specified as either USER or SYSTEM.

SETRP_REASON overrides the reason code of the original ABEND. The reason argument is the new reason code.

SETRP_RETRY specifies the address of an ESTAE retry. The retry argument is the address at which execution of the retry routine is to begin. To retry the ABEND in C code, the retry argument should be a call to the bldretry function, whose first argument is a jump buffer defining the retry point. The fresdwa argument must be FRESDWA or NOFRESDWA and must indicate whether the SDWA should be freed before control is passed to the retry routine.

CAUTION

The SETRP macros should be used only with the Systems Programming Environment (SPE).

EXAMPLE

See the example for ESTAE.

RELATED FUNCTIONS

ESTAE, bldretry

STATUS -- Halt or Resume a Subtask

SYNOPSIS

 #include <ostask.h>

 void STATUS(action, void **tcbaddr);

DESCRIPTION

The SAS/C STATUS macro implements the functionality of the MVS Assembler STATUS macro. The action argument specifies whether the task is to be stopped or started and must be either START or STOP. The tcbaddr argument is a pointer to a fullword containing the address of the TCB to be started or stopped.

RELATED FUNCTIONS

ATTACH

STIMER -- Define a Timer Interval

SYNOPSIS

 #include <spetask.h>

 void STIMER(type, void *exit, unit, void *intvl);

DESCRIPTION

The SAS/C STIMER macro implements the functionality of the MVS Assembler STIMER macro. This macro is supported only with the Systems Programming Environment (SPE).

type: specifies the type of timer interval and must be either TASK, WAIT or REAL.
exit: specifies the address of code to be called as a timer exit when the interval is complete. An exit address of 0 means that no exit is to be called. The exit argument should ordinarily be specified as a call to the bldexit function, whose first argument is the address of the C function which is to be defined as the exit.
unit: specifies the units of the timer interval and must be either TUINTVL, BINTVL, MICVL, DINTVL, GMT or TOD.
intvl: is a pointer to an area specifying the time interval or time of expiration. The size and interpretation of this data depends on the unit, as described in Application Development Reference: Services for Assembler Language Programs available from IBM.

CAUTIONS

Use of the SAS/C STIMER macro in code that uses the full run-time library will interfere with library timer handling. Additionally, the bldexit function cannot be used with the full run-time library.

Similar functionality to STIMER can be obtained with the full library using the functions alarm, sleep, or clock.

RELATED FUNCTIONS

TTIMER, STIMERM, alarm, clock, sleep

STIMERM... -- Define, Test, or Cancel a Real Time Interval

SYNOPSIS

 #include <spetask.h>

 int STIMERM_SET(void *exit, void *parm, unsigned *idaddr, unit,
                 void *intvl, wait);

 int STIMERM_TEST(unsigned *idaddr, unit, void *intvl);

 int STIMERM_CANCEL(unsigned *idaddr, unit, void *intvl);

DESCRIPTION

The SAS/C STIMERM macros implement the functionality of the MVS Assembler STIMERM macro. These macros are supported only with the Systems Programming Environment (SPE).

STIMER_SET: specifies a real-time interval and how its expiration is to be handled. The exit argument is the address of code to be called as a timer exit when the interval is complete. The exit argument should ordinarily be specified as a call to the bldexit function, whose first argument is the address of the C function which is to be defined as the exit. The parm argument is a pointer to be made available to the exit routine when it runs. The idaddr argument is the address of an unsigned area where an id value can be stored by the STIMERM SVC. The unit argument must TUINTVL, BINTVL, MICVL, DINTVL, GMT, or TOD. The intvl argument should be a pointer to an area specifying the time interval or time of expiration. The size and interpretation of this data depends on the unit, as described in the IBM publication Services for Assembler Language Programs. The wait argument indicates whether the program should be suspended until the interval expires and must be either WAIT or NOWAIT. If you specify WAIT, the exit argument should be 0.
STIMER_TEST: tests the amount of time remaining of a real-time interval defined by STIMERM_SET. The idaddr argument specifies the address of an unsigned area containing the ID of the interval to be tested. The unit argument indicates the format in which the remaining time is to be stored and must be either TU or MIC. The intvl argument specifies the address where the amount of time remaining should be stored. The size and interpretation of this data depends on the unit, as described in the IBM publication Application Development Reference: Services for Assembler Language Programs.
STIMERM_CANCEL: cancels one or more time intervals established with STIMERM_SET. The idaddr argument specifies the address of an area containing the ID of the timer interval to be cancelled. idaddr may also be specified as 0 to cancel all intervals. The unit argument specifies the form in which the remaining time is to be stored and must be either TU or MIC. The intvl address specifies the address where the amount of time remaining in the cancelled interval should be stored. It should be specified as 0 if idaddr is also 0. The size and interpretation of the intvl data depends on the unit, as described in the IBM publication Application Development Reference: Services for Assembler Language.

RETURN VALUE

The STIMERM macros return the value that is returned in register 15 by the assembler STIMERM macro.

CAUTIONS

The STIMERM macros should not be used in code that runs with the full library since the bldexit function cannot be used in such programs.

Similar functionality to STIMERM can be obtained with the full library using the functions alarm or sleep.

RELATED FUNCTIONS

STIMER, TTIMER, alarm, sleep

TPUT/TGET -- Terminal I/O via SVC 93

SYNOPSIS

 #include <tput.h>

 int TPUT(void *buffer, unsigned short bufsiz,
          unsigned int options );
 int TPUT_ASID(void *buffer, unsigned short bufsiz,
               unsigned short asid, unsigned int options );
 int TPUT_USERID(void *buffer, unsigned short bufsiz,
                 char *userid, unsigned int options );
 int TGET(void *buffer, unsigned short bufsiz,
          unsigned int options );

DESCRIPTION

These functions simulate the MVS TPUT and TGET Assembler macros. TPUT sends a line of output to the terminal. TPUT_ASID and TPUT_USERID can be used for interuser communication. TGET reads a line of input from the terminal.

Each macro causes the compiler to generate code to load the appropriate values into registers 0, 1, and 15, and then to generate SVC 93. The use of each argument is explained below:

buffer: is a pointer to the output line (TPUT, TPUT_ASID, and TPUT_USERID) or to the input buffer (TGET).
bufsiz: specifies the length of the output line or the length of the input buffer.
options: is a set of option flags. Each macro corresponds to a value of one of the assembler macro parameters. All option flags are defined as macros in <tput.h>. Table 4.3 lists the options that can be used in each macro. Use 0 as the option argument to specify that all of the defaults should be taken.
asid: is the address space identifier of the target userid.
userid: is a pointer to an 8-byte char array that contains the target userid. The userid must be uppercase, left-adjusted, and padded on the right with blanks if necessary.

If the macro name _AMODE31 has been defined prior to including the <tput.h> header file, the macros generate a call to the _TPUT function.

RETURN VALUE

The macros return the value in register 15 after the SVC 93 completes.

ERRORS AND DIAGNOSTICS

The possible errors are the same as when the TPUT or TGET Assembler macros are used in an assembler language program.

CAUTIONS

PORTABILITY

None of the macros are portable.

IMPLEMENTATION

By default, the macros generate R-form invocations of TPUT and TGET. This form is not supported by MVS/XA in 31-bit addressing mode.

This function copies output data to a below-the-line buffer before transmission (for TPUT) or reads input data into a below-the-line buffer and then copies it to the buffer pointed to by buffer (for TGET).

If _AMODE31 has been defined, the maximum transmission size is 1024 bytes. This limit can be changed by recompiling L$UTPIO.

EXAMPLE

    /* Send greetings.  Use the default options. */
 rc = TPUT("Hello, world!",13,0);

Table 4.3 shows the macro names defined as option flags for the TPUT and TGET macros. In the macro columns, a yes entry indicates that the flag can be used in the options argument for the macro. A no entry indicates that the flag cannot be used. An ignored entry indicates that the flag is ignored if used.

Table 4.3: (Macros Defined for TPUT and TGET Options)

   Option    TPUT      TPUT_ASID   TPUT_USERID   TGET

   _EDIT      yes       yes         yes           yes

   _ASIS      yes       yes         yes           yes

   _CONTROL   yes       yes         yes           no

   _FULLSCR   yes       yes         yes           no

   _WAIT      yes       yes         yes           yes

   _NOWAIT    yes       yes         yes           yes

   _HOLD      yes       ignored     ignored       no

   _NOHOLD    yes       ignored     ignored       no

   _BREAKIN   yes       yes         yes           no

   _NOBREAK   yes       yes         yes           no

   _HIGHP     ignored   yes         yes           no

   _LOW       ignored   yes         yes           no

TTIMER -- Test or Cancel a Timer Interval

SYNOPSIS

 #include <spetask.h>

 int TTIMER(cancel, unit, void *area);

DESCRIPTION

The TTIMER macro implements the functionality of the MVS Assembler TTIMER macro. This macro is supported only with the Systems Programming Environment (SPE).

The cancel argument indicates whether the timer interval is to be cancelled or merely tested and must be either CANCEL or NOCANCEL. The unit argument specifies the units in which remaining time should be stored and must be either TU or MIC. The addr argument addresses an area where the remaining time should be stored. The size of this area is determined by the unit specification, as described in the IBM publication Application Development Reference: Services for Assembler Language Programs.

RETURN VALUE

TTIMER returns the value that is returned in register 15 by the assembler TTIMER macro.

CAUTIONS

Use of the TTIMER macro in code that uses the full run-time library interferes with library timer handling.

Similar functionality to TTIMER can be obtained with the full library using the functions alarm, sleep, or clock.

RELATED FUNCTIONS

STIMER, STIMERM, alarm, clock, sleep

typlin -- Invoke the CMS TYPLIN Function

SYNOPSIS

 #include <wrterm.h>

 int typlin(char *buffer, short bufsiz, char color, char edit);

DESCRIPTION

typlin invokes the CMS TYPLIN function to type a line of output to the terminal. The typlin macro creates a TYPLIN parameter list and generates an inline SVC 202. A description of each of the arguments follows:

buffer: is a pointer to the string to be typed.
bufsiz: is the length of the string.
color: is one of two values specifying the color in which the string will be typed if the terminal is a typewriter terminal and the typewriter has a two-color ribbon. Use either WR_RED or WR_BLACK, both of which are defined as macros in <wrterm.h>.
edit: is a code specifying the editing to be performed by the TYPLIN function before the string is displayed. Valid values for this argument are defined as macros in <wrterm.h>. Each macro corresponds to a value for the EDIT keyword operand in the WRTERM assembler language macro. The macros WR_EDIT_YES, WR_EDIT_NO, and WR_EDIT_LONG correspond to EDIT=YES, EDIT=NO, and EDIT=LONG, respectively.

RETURN VALUE

typlin returns the value in register 15 when the TYPLIN function returns.

CAUTIONS

In XA CMS or ESA, typlin can be used only in 24-bit addressing mode.

ERRORS AND DIAGNOSTICS

The possible errors are the same as when the TYPLIN function is used in an assembler language program.

PORTABILITY

typlin is not portable.

IMPLEMENTATION

typlin creates a TYPLIN parameter list in the CRABTAUT work area. See SAS/C Compiler and Library User's Guide, Fourth Edition for more information about CRABTAUT.

EXAMPLE

 void dispval(int n)
    {
    char *line[130]  ;
    int len, rc;
       /* Format and display the value of the input parameter. */
    len = format(line,"The value of n is %d",n);
    (void) typlin(line,len,WR_BLACK,WR_EDIT_NO);
    }

WAIT -- Wait for the POST of One or More ECB's

SYNOPSIS

 #include <ostask.h>

 void WAIT1(unsigned *ecbaddr);

 void WAITM(int n, unsigned **ecblist);

DESCRIPTION

The SAS/C WAIT macros implement the functionality of the MVS Assembler WAIT macro.

WAIT1 waits for a single ECB to be posted. The ecbaddr argument addresses the ECB.

WAITM waits for one or more of a list of ECBs to be posted. The argument n to WAITM specifies the number of ECBs which must be posted before execution resumes. The argument ecblist points to a list of ECB addresses to be waited on. The last address in the list must be flagged by turning on the high-order bit of the address.

CAUTION

WAIT1 and WAITM can be used in either an SPE environment or a full run-time library environment. However, when using the full library, you should consider using ecbsuspend to wait for an ECB POST because this also allows the wait to be interrupted by a C signal.

EXAMPLE

 #include <ostask.h>

 unsigned myecb = 0, yourecb = 0, theirecb = 0;

 unsigned *ecblist[3];

 ecblist[0] = &myecb;
 ecblist[1] = &yourecb;
 ecblist[2] = (unsigned *) (0x80000000 | (unsigned) &theirecb));
 WAITM(1, ecblist);                   /* Wait on one of three ECBs. */

RELATED FUNCTIONS

ecbsuspend, POST

waitrd -- Invoke the CMS WAITRD Function

SYNOPSIS

 #include <wrterm.h>

 int waitrd(char *inbuf, short inbufsz, char code1, char code2,
            char *pbuf, int pbufsz, int *inlen);

DESCRIPTION

waitrd invokes the CMS WAITRD function to read a line of input from the program stack or terminal input buffer. The waitrd macro creates a WAITRD parameter list and generates an inline SVC 202. A description of each of the arguments follows:

inbuf: is a pointer to a buffer into which the input line is read.
inbufsz: is the length of the input buffer.
code1: specifies the processing performed on lines read from the terminal input buffer. <wrterm.h> contains definitions for a number of macros, each of which corresponds to a WAITRD function code1 parameter. Table 4.4 lists the macro names and the associated code1 values.
code2: specifies additional processing codes. Again, <wrterm.h> contains definitions for a number of macros, each of which corresponds to a WAITRD function code2 parameter. Table 4.5 lists the macro names and the associated code2 values. For an explanation of each of the code1 and code2 values, refer to Chapter 1 in VM/SP Command and Macro Reference appropriate for your release.
pbuf: is a pointer to a prompt string. If code2 is PROMPT_NO, this argument is ignored.
pbufsz: is the length of the prompt string. If code2 is PROMPT_NO, this argument is ignored.
inlen: is a pointer to an int where the length of the input string is stored.

RETURN VALUE

waitrd returns the value in register 15 when the WAITRD function returns.

CAUTION

In XA CMS or ESA, waitrd can only be used in 24-bit addressing mode.

ERRORS AND DIAGNOSTICS

The possible errors are the same as when the WAITRD function is used in an assembler language program.

PORTABILITY

waitrd is not portable.

IMPLEMENTATION

The waitrd macro creates a WAITRD parameter list in the CRABTAUT work area. (See the SAS/C Compiler and Library User's Guide, Fourth Edition for more information about CRABTAUT.)

EXAMPLE

    /* Read an input line of at most 25 characters */
    /* from the terminal.                          */
 char *name[25] ;
 char *prompt = "Please enter your name."
 int rc;
 int inlen;

    /* Ask for the input to be  */
    /* translated to uppercase. */
 rc = waitrd(name,sizeof(name),STACK_UPCASE,PROMPT_YES,
      prompt, strlen (prompt),&inlen);

WAITT -- Simulate the WAITT Assembler Language Macro

SYNOPSIS

 #include <wrterm.h>

 void WAITT(void);

DESCRIPTION

WAITT simulates the CMS WAITT assembler language macro. WAITT creates a CMS CONWAIT function parameter list and generates an inline SVC 202. If the symbol BIMODAL is defined, SVC 204 is used in place of SVC 202, which is necessary for use in 31-bit addressing mode.

RETURN VALUE

WAITT does not return a value.

PORTABILITY

WAITT is not portable.

WRTERM -- Simulate the WRTERM Assembly Language Macro

SYNOPSIS

 #include <wrterm.h>

 int WRTERM(char *buffer, short bufsiz);

DESCRIPTION

WRTERM simulates the WRTERM assembly language macro. The WRTERM macro invokes the typlin macro to produce a parameter list that is equivalent to using the WRTERM assembly language macro with all parameters allowed to default. If the symbol BIMODAL is defined, WRTERM generates an equivalent to the CMS LINEWRT macro and, therefore, can be used in 31-bit addressing mode.

RETURN VALUE

WRTERM returns the value in register 15 when the TYPLIN or LINEWRT function returns.

ERRORS AND DIAGNOSTICS

The possible errors are the same as when the WRTERM or LINEWRT macro is used in an assembly language program.

PORTABILITY

WRTERM is not portable.

IMPLEMENTATION

The definition of WRTERM if BIMODAL is not defined is as follows:

 #define WRTERM(bf,l) typlin(bf,l,WR_BLACK,WR_EDIT_NO)

EXAMPLE

 void dispval(int n)
    {
    char *line[130]  ;
    int len, rc;

       /* equivalent to the example for the typlin macro */
    len = format(line,"The value of n is %d",n);
    (void) WRTERM(line,len);
    }

MVS Multitasking and Other Low-Level System Interfaces

Introduction

Multitasking SAS/C Applications

Compatibility Changes

Function Descriptions

ABEND -- Abnormally Terminate a Program

SYNOPSIS

DESCRIPTION

CAUTIONS

EXAMPLE

RELATED FUNCTIONS

ATTACH -- Create a New Subtask

SYNOPSIS

DESCRIPTION

RETURN VALUE

CAUTIONS

IMPLEMENTATION

EXAMPLE

RELATED FUNCTIONS

CHAP -- Change a Task's Priority

SYNOPSIS

DESCRIPTION

CMSSTOR -- Allocate or Free Storage

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS AND DIAGNOSTICS

CAUTION

PORTABILITY

SEE ALSO

DEQ -- Release an Enqueued Resource

SYNOPSIS

DESCRIPTION

RETURN VALUE

EXAMPLE

RELATED FUNCTIONS

DETACH -- Remove a Subtask from the System

SYNOPSIS

DESCRIPTION

RETURN VALUE

EXAMPLE

RELATED FUNCTIONS

DMSFREE -- Allocate or Free DMSFREE Storage

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS AND DIAGNOSTICS

CAUTION

PORTABILITY

SEE ALSO

ENQ -- Wait for a Resource to Become Available

SYNOPSIS

DESCRIPTION

RETURN VALUE

EXAMPLE

RELATED FUNCTIONS

ESTAE -- Define an Abnormal Termination Exit

SYNOPSIS

DESCRIPTION

RETURN VALUE

CAUTIONS

EXAMPLE

RELATED FUNCTIONS

GETMAIN/FREEMAIN -- Allocate or Free Virtual Storage

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS AND DIAGNOSTICS

CAUTIONS

PORTABILITY

IMPLEMENTATION

SEE ALSO

EXAMPLE

POST -- Post an ECB

SYNOPSIS

DESCRIPTION

RELATED FUNCTIONS

RDTERM -- Simulate the RDTERM Assembler Language Macro

SYNOPSIS

DESCRIPTION