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
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. )
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.
With Release 5.50, some of the symbols defined in the
The changes shown in Table 4.1 apply to the TPUT and TGET macros defined in .
Table 4.1: 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 .
Old Form New Form
ASYNCH _ASYNCH NOR13 _NOR13 FLOATSV _FLOATSV AMODE _AMODE
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.
#include void ABEND(unsigned code, unsigned reason, dumpopt, sysopt);
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.
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.
#include ABEND(0xbad,0,DUMP,SYSTEM);
#include int ATTACH(void **tcbaddr, . );
void etxr(void *tcbaddr);
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.
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.
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.
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.
This example attaches the SAS/C Compiler out of the DDname SASCLIB, and uses the WAIT1 function to wait for it to complete.
#include #include #include DCB_t *tasklib; unsigned myecb; int rc; void *subtcb; void *plist [1]; /* parm list for compiler */ struct < short len; char options[8]; >argument = ; 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);
#include void CHAP(int prio, void **tcbaddr);
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.
#include int CMSSTOR_OBT(unsigned int bytes, void **loc, char *subpool, charoptions, int erresp); int CMSSTOR_REL(unsigned int bytes, void *loc2, char *subpool, charoptions, int erresp);
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 . 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
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 .
The possible errors are the same as when the CMSSTOR Assembler macro is used in an assembler language program.
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.
#include int DEQ(char *qname, char *rname, int rlen, scope, ret);
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.
#include int DETACH(void **tcbaddr, option);
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.
#include int DMSFREE(unsigned int dwords, void **loc, charoptions, int erresp); int DMSFREE_V(unsigned int dwords, unsigned int min, void **loc, unsigned int *got, charoptions, int erresp); int DMSFRET(unsigned int dwords, void *loc2, char msg, int erresp);
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 . 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
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 .
The possible errors are the same as when the DMSFREE or DMSFRET assembler macros are used in an assembly language program.
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.
#include int ENQ(char *qname, char *rname, excl, int rlen, scope, ret);
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.
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); >
#include int ESTAE(void *exit, create, void *param, asynch, term); int ESTAE_CANCEL(void);
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.
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.
#include #include #include 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; >
#include int GETMAIN_C(unsigned int length, int subpool, intoptions, void **loc); int GETMAIN_U(unsigned int length, int subpool, intoptions); int GETMAIN_V(unsigned int max, unsigned int min, int subpool, intoptions, void **loc, unsigned int *alloc); int FREEMAIN( void **loc, unsigned int length, int subpool, intoptions);
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 .
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.
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 .
The possible errors are the same as if the GETMAIN or FREEMAIN assembler macros are used in an assembly language program.
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 .
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.
#include void POST(unsigned *ecbaddr, unsigned code);
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.
#include int RDTERM(char *inbuf, short inbufsz, int *inlen);
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.
The possible errors are the same as when the RDTERM or LINERD macro is used in an assembler language program.
#define RDTERM(b,l,rl) waitrd(b,l,STACK_MIXED,PROMPT_NO,0,0,rl)
char *line[130] int len, rc; /* Read up to 130 characters with no prompt and no editing. */ rc = RDTERM(line,sizeof(line),&len);
#include 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);
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.
#include void STATUS(action, void **tcbaddr);
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.
#include void STIMER(type, void *exit, unit, void *intvl);
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.
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 .
#include 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);
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 .
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 .
#include int TPUT(void *buffer, unsigned short bufsiz, unsigned intoptions); int TPUT_ASID(void *buffer, unsigned short bufsiz, unsigned short asid, unsigned intoptions); int TPUT_USERID(void *buffer, unsigned short bufsiz, char *userid, unsigned intoptions); int TGET(void *buffer, unsigned short bufsiz, unsigned intoptions);
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 . 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 header file, the macros generate a call to the _TPUT function.
The possible errors are the same as when the TPUT or TGET Assembler macros are used in an assembler language program.
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 possibly undesirable results.
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.
/* 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
#include int TTIMER(cancel, unit, void *area);
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.
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 .
#include int typlin(char *buffer, short bufsiz, char color, char edit);
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
The possible errors are the same as when the TYPLIN function is used in an assembler language program.
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.
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); >
#include void WAIT1(unsigned *ecbaddr); void WAITM(int n, unsigned **ecblist);
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.
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.
#include 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. */
#include int waitrd(char *inbuf, short inbufsz, char code1, char code2, char *pbuf, int pbufsz, int *inlen);
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.
The possible errors are the same as when the WAITRD function is used in an assembler language program.
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.)
/* 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);
Table 4.4: (Macros Defined for the waitrd code1 Argument)
Macro Name Corresponding Value
RD_EDIT_YES U RD_EDIT_NO T RD_EDIT_PHYS X RD_EDIT_PAD S RD_EDIT_UPCASE V RD_EDIT_NOINPT Y STACK_UPCASE Z STACK_MIXED W ATTREST_YES * ATTREST_NO $
Table 4.5: (Macros Defined for the waitrd code2 Argument)
Macro Name Corresponding Value
PROMPT_DIRECT B TYPE_DIRECT D PROMPT_YES P PROMPT_NO 0
#include void WAITT(void);
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.
#include int WRTERM(char *buffer, short bufsiz);
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.
The possible errors are the same as when the WRTERM or LINEWRT macro is used in an assembly language program.
#define WRTERM(bf,l) typlin(bf,l,WR_BLACK,WR_EDIT_NO)
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); >