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.)
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:
malloc
or
palloc
in one framework
and free it with free
or pfree
in another.
stdout
or stderr
is a disk
file, lost output and or I/O errors may occur.
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.
<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
#include <spetask.h> void ABEND(unsigned code, unsigned reason, dumpopt, sysopt);
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.
BAD
and reason code 0
.
#include <spetask.h> ABEND(0xbad,0,DUMP,SYSTEM);
abend
, abort
#include <ostask.h> int ATTACH(void **tcbaddr, ...);
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:
_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.
_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.)
_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.
_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.
_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.)
_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.
_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.
_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.
_Aszerono
keyword is equivalent to the Assembler keyword
SZERO=NO. This keyword does not take a value. The next argument
should be another keyword.
_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.)
_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.
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.
_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.
ATTACH
function is implemented by the source module L$UATTA.
The SPE implementation of ETXR exits is provided by the source module
L$UAEOT.
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);
DETACH
, oslink
, system
#include <ostask.h> void CHAP(int prio, void **tcbaddr);
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 <cmsstor.h> 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);
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
CMSSTOR_OBT
or released by CMSSTOR_REL
.
loc
void *
where the address of the first
byte of allocated storage can be stored.
loc2
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
<cmsstor.h>
.
There are three types of option flags,
corresponding to the assembler macro keyword parameters MSG,
LOC, and
BNDRY.
MSG_YES
and MSG_NO
.
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_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
<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.
CMSSTOR_OBT
, the
value in register 1 is stored in the void *
pointed to by
loc
.
#include <ostask.h> int DEQ(char *qname, char *rname, int rlen, scope, ret);
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.
DEQ
macro returns the same value as the return code from
the assembler DEQ macro.
ENQ
.
ENQ
#include <ostask.h> int DETACH(void **tcbaddr, option);
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.
DETACH
macro returns the value returned in register 15 by the
assembler DETACH macro.
ATTACH
macro earlier in this chapter.
ATTACH
#include <dmsfree.h> 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);
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
DMSFREE
or DMSFREE_V
or released by DMSFRET
.
min
loc
void *
where the address of the first
byte of allocated free storage can be stored.
loc2
got
unsigned int
where the number of
doublewords actually allocated by a variable request can be stored.
options
<dmsfree.h>
.
There are three types of option flags,
corresponding to the assembler macro keyword parameters TYPE, AREA, and
MSG.
TYPE_NUC
specifies NUCLEUS free storage,
and TYPE_USER
specifies USER free storage.
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_YES
and MSG_NO
.
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_YESUse 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
erresp
<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.
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
.
#include <ostask.h> int ENQ(char *qname, char *rname, excl, int rlen, scope, ret);
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.
ENQ
macro returns the same value as the return code from
the assembler ENQ macro.
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); }
DEQ
#include <spetask.h> int ESTAE(void *exit, create, void *param, asynch, term); int ESTAE_CANCEL(void);
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
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
asynch
ASYNCH
or NOASYNCH
, to indicate whether
or not asynchronous interrupts are allowed in the exit.
term
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.
ESTAE
and ESTAE_CANCEL
macros return the ESTAE assembler
macro return code in register 15.
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.
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; }
bldexit
, SETRP
, signal
#include <getmain.h> 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
);
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
GETMAIN_
macros or released by FREEMAIN
.
subpool
options
<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
void *
where the address of the
allocated storage area can be stored.
max,min
alloc
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 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>
.
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.
/* 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); }
#include <ostask.h> void POST(unsigned *ecbaddr, unsigned code);
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.
WAIT
#include <wrterm.h> 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.
RDTERM
returns the value in register 15 when the
WAITRD
or LINERD
function returns.
RDTERM
is not portable.
RDTERM
if BIMODAL
is not defined is
as follows:
#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 <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);
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.
SETRP
macros should be used only with the Systems Programming
Environment (SPE).
ESTAE
.
ESTAE
, bldretry
#include <ostask.h> void STATUS(action, void **tcbaddr);
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.
ATTACH
#include <spetask.h> void STIMER(type, void *exit, unit, void *intvl);
STIMER
macro implements the functionality of the MVS
Assembler STIMER macro. This macro is supported only with the Systems
Programming Environment (SPE).
type
TASK
,
WAIT
or REAL
.
exit
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
TUINTVL
, BINTVL
, MICVL
, DINTVL
, GMT
or TOD
.
intvl
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
.
TTIMER
, STIMERM
, alarm
, clock
, sleep
#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);
STIMERM
macros implement the functionality of the MVS
Assembler STIMERM macro. These macros are supported only with the
Systems Programming Environment (SPE).
STIMER_SET
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
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
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.
STIMERM
macros return the value that is returned in register
15 by the assembler STIMERM macro.
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
.
STIMER
, TTIMER
, alarm
, sleep
#include <tput.h> 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
);
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
TPUT
,
TPUT_ASID
, and TPUT_USERID
)
or to the input buffer (TGET
).
bufsiz
options
<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
userid
char
array that contains
the target userid. The userid must be uppercase,
left-adjusted, and padded on the right with blanks if necessary.
_AMODE31
has been defined prior to including
the <tput.h>
header file, the macros generate a call to the
_TPUT
function.
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 <spetask.h> int TTIMER(cancel, unit, void *area);
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.
TTIMER
returns the value that is returned in register 15 by the
assembler TTIMER macro.
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
.
STIMER
, STIMERM
, alarm
, clock
, sleep
#include <wrterm.h> 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
bufsiz
color
WR_RED
or WR_BLACK
,
both of which are
defined as macros in <wrterm.h>
.
edit
<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.
typlin
returns the value in register 15 when the TYPLIN
function returns.
typlin
can be used only in 24-bit addressing
mode.
typlin
is not portable.
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 <ostask.h> void WAIT1(unsigned *ecbaddr); void WAITM(int n, unsigned **ecblist);
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.
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 <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. */
ecbsuspend
, POST
#include <wrterm.h> 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
inbufsz
code1
<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
<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
code2
is PROMPT_NO,
this argument is ignored.
pbufsz
code2
is PROMPT_NO,
this argument is ignored.
inlen
int
where the length of the input string
is stored.
waitrd
returns the value in register 15 when the WAITRD
function returns.
waitrd
can only be used in 24-bit addressing
mode.
waitrd
is not portable.
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 <wrterm.h> 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.
WAITT
does not return a value.
WAITT
is not portable.
#include <wrterm.h> 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.
WRTERM
returns the value in register 15 when the TYPLIN
or LINEWRT function returns.
WRTERM
is not portable.
WRTERM
if BIMODAL
is
not defined is as follows:
#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); }
Copyright (c) 1998 SAS Institute Inc. Cary, NC, USA. All rights reserved.