Chapter Contents

Previous

Next

The osdynalloc Function

Portability

SAS/C extension

SYNOPSIS

#include <os.h>

int osdynalloc(int action, char *keywords, char *libmsgbuf, ...);

DESCRIPTION

osdynalloc is used to invoke the MVS dynamic allocation SVC (SVC 99). You can use osdynalloc to allocate, free, concatenate or deconcatenate data sets, as well as to return information about existing allocations. MVS dynamic allocation is described in detail in the IBM publication MVS/ESA Application Development Guide: Authorized Assembler Language Programs. Unless you are already familiar with dynamic allocation, you should read the sections of this book discussing dynamic allocation to be aware of the restrictions and other complexities of this powerful service.

The action argument to osdynalloc specifies the required dynamic allocation action. The names of the actions (defined in <os.h> ) are:

DYN_ALLOC	allocate a data set
DYN_FREE	free a data set or DDname
DYN_CONCAT	concatenate several DDnames
DYN_DECONCAT	deconcatenate a concatenated DDname
DYN_DDALLOC	allocate a data set by DDname
DYN_NOTINUSE	mark allocations not in use
DYN_INQUIRE	obtain information about current allocations

Note:    The DYN_DDALLOC action is very specialized. See IBM documentation for information about the use of DYN_DDALLOC and how it differs from DYN_ALLOC .  

The keywords argument is a pointer to a character string containing a list of keywords. The keywords specify parameters for the request, for instance the name of a data set to be allocated or the address of a variable in which to store a DDname. See below for some simple examples of keyword strings.

The libmsgbuf argument specifies the address of an array of characters (containing at least 128 bytes) in which any error message generated by the library is to be stored. If libmsgbuf is specified as NULL , the library writes any error messages to stderr , and the texts are not returned to the caller. Note that in SPE if libmsgbuf is specified as NULL , no messages will be written unless the $WARNING routine has been replaced, as described in the SAS/C Compiler and Library User's Guide. See "DIAGNOSTICS" later in this section for further information on error handling.

Additional arguments to osdynalloc may optionally be specified after the libmsgbuf argument. These arguments are used to complete the keywords string, as shown in the examples below.

Here are a few simple calls to osdynalloc , to show how keyword strings are assembled:

rc = osdynalloc(DYN_ALLOC, "ddn=master,dsn=billing.master.data,disp=shr", NULL);

allocates the data set BILLING.MASTER.DATA with disposition SHR to the DDname MASTER.

rc = osdynalloc(DYN_FREE, "ddn=master,disp=delete,reason=?", NULL, & reason);

frees the DDname MASTER with disposition DELETE, and stores the error reason code in the integer reason .

rc = osdynalloc(DYN_CONCAT, "ddn=(syslib,syslib1,syslib2),perm", NULL);

concatenates the DDnames SYSLIB, SYSLIB1 and SYSLIB2, and marks the concatenation as permanent.

rc = osdynalloc(DYN_INQUIRE, "ddn=master,retdsn=?,retdsorg=?,msgcount=?,errmsgs=?", libmsgbuf, dsnbuf, & dsorg, & number_msgs, & mvsmsgbuf);

finds the name of the data set allocated to the DDname MASTER and its organization, and stores the results in the variables dsnbuf and dsorg . If the request fails, any library message is stored in libmsgbuf , and the address of an MVS message buffer is stored in mvsmsgbuf . Also, the number of MVS messages is stored in number_msgs .

The keywords argument to osdynalloc is just a list of items separated by commas. Each item is identified by a keyword, like "ddn" , "disp" and "perm" in the examples above. The permitted keywords are determined by the particular action requested by action , and are described in tables appearing later in this description. Each keyword in the string is translated by osdynalloc into a single dynamic allocation text unit. (See Authorized Assembler Language Programs for further information on text units.) Additional keywords are accepted in calls to osdynalloc , regardless of action , such as "reason" and "errmsgs" in the examples above. These keywords correspond to fields in the SVC 99 request block, and generally request special processing options or deal with error-handling.

Syntactically, there are three kinds of keywords items, as follows:

• single value items, like "disp=shr" . These items have the form " keyword = value " .

• multiple value keywords, like "ddn=(syslib,syslib2)" . These items have the form " keyword =( value1 , value2 ,...)" . If there is only one value, the parentheses can be left off.

• switch items, like "dummy" . These items have a keyword, but no value.

Any keyword value may be specified as the single character "?" . This indicates that the actual keyword value is present in the argument list as an additional argument. The order of any additional arguments is the same as the order of the corresponding keywords in the keywords string. Note that for multiple value keywords, each ? corresponds to a single value. That is, you could have a call like the following:

osdynalloc(DYN_ALLOC, "...volser=(?,?),...", NULL, "VOLUM1", "VOLUM2")

However, you cannot have a call like the following:

osdynalloc(DYN_ALLOC, "...volser=?,...", NULL, "(VOLUM1,VOLUM2)")

The keywords accepted by osdynalloc are classified into various sorts based on the type of the associated values:

String values

are associated with keywords, such as "member=name" , that have a value which is a character string. An argument supplied using the "?" convention should have type char * . With a few exceptions, string values are automatically translated to upper-case.

Dsname values

are associated with keywords, such as "dsn=.project.c" , that have a string value that is interpreted as a data set name. If the name begins with a period, the name is completed by prepending the user's TSO prefix or (in batch) the userid.

Reserved-word values

are associated with keywords, such as "disp=old" , that have a string value which is limited to a prescribed set of values. Except for this limitation, they are treated as string values. The values permitted for particular keywords are the values permitted for the corresponding JCL parameter, unless stated otherwise below.

Integer values

are associated with keywords, such as "blksize=800" , that have a value that is a decimal or hexadecimal string. An argument supplied using the "?" convention should have type int .

Pointer values

are associated with keywords, such as "retddn=0xf0328" , that have a value that is a decimal or hexadecimal address, pointing to an area where information is to be returned. This must be the address of a variable of the appropriate type, either int for numeric information, or a char array for string information. In many cases, the values returned via pointers are encoded. For instance, a dsorg (data set organization) is returned as an integer with different bits set depending on the actual file organization. Information on interpreting these values is given in the IBM book cited above.

There are also keywords with specialized value representations (such as "secmodel=" and "expdt=" ). These are discussed individually in the keyword tables below.

RETURN VALUE

osdynalloc returns 0 if it was successful. It returns a negative value if an error was detected by the C library before the dynamic allocation SVC could be invoked. In this case, a diagnostic message will have been stored in libmsgbuf if this address is not NULL . If SVC 99 is called and fails, osdynalloc returns the value returned in register 15 by SVC 99, as described in Authorized Assembler Language Programs. Additional information about the error can be obtained by use of keywords such as "reason" , "inforeason" and "errmsgs" , as described in SVC 99 Request Block Keywords.

DIAGNOSTICS

osdynalloc is subject to three different sorts of errors.

The first sort is errors detected before calling SVC 99. Examples of such errors are unrecognized keywords or memory allocation failures. The SAS/C library generates diagnostics for these failures and either writes them to stderr or returns them to the user via the libmsgbuf argument. SVC 99 is not issued if one of these errors occurs.

The second sort is errors detected by SVC 99. Information about these errors is returned in the osdynalloc return code, and additional information can be obtained via keywords like "reason" . The library never diagnoses any of these errors. The "errmsgs" keyword may additionally be specified to request that one or more messages about a failure be returned to the caller. These messages are obtained by a call to the IBM routine IEFDB476. Note that these messages are frequently unsuitable for particular applications. (For example, the message for an out-of-disk-space situation exhorts the user to " USE THE DELETE COMMAND TO DELETE UNNEEDED DATA SETS ", even if the program is not running under TSO.) Also note that the "issuemsg" keyword can be used to request that dynamic allocation issue these messages itself, using either the PUTLINE service or the WTO SVC.

The third sort of error is errors detected by IEFDB476. These errors are not diagnosed by the library or by MVS, and do not affect the osdynalloc return code. The IEFDB476 error codes can be accessed using the "msgerror" and "msgreason" keywords.

IMPLEMENTATION

osdynalloc is implemented by the L$UDYNA module, which is provided in source form. You can modify this module to add or delete keywords. You might wish to add keywords if functionality is added to SVC 99 by a new release of MVS. You might wish to delete keywords if you have a storage-constrained application which does not need to use some of the more obscure dynamic allocation options or keywords.

KEYWORD TABLES

SVC 99 Request Block Keywords shows all the keywords that can be used for any call to osdynalloc , regardless of which action is specified. These keywords are not translated to text units. Rather, they cause information to be stored in the SVC 99 request block (S99RB) or request block extension (S99RBX). Most options can be identified by more than one keyword. This is intended to assist you to easily locate the keywords you need. Short forms correspond to the field names defined in Authorized Assembler Language Programs, as well as longer names which may be more understandable or easier to recall.

Note that some options in this table can only be used by authorized programs, as described in the IBM manual.

SVC 99 Request Block Keywords

Identifier	RB Field	Value	Description	Notes
condenq cnenq	S99CNENQ	none	Conditionally ENQ on TIOT
cppl ecppl	S99ECPPL	void*	TSO CPPL address
errmsgs errmsg ermsg emsgp	S99EMSGP	dyn_msgbuf**	Error message buffer return address	(1)
errorcode errorreason reasoncode reason error	S99ERROR	int*	Error reason code return address
flags1 flag1 flg1	S99FLAG1	int	First S99RB flag byte	(2)
flags2 flag2 flg2	S99FLAG2	int	Second S99RB flag byte	(2)
freereason freeerror ercf	S99ERCF	int*	Message free error code
gdglocate gdgnt	S99GDGNT	none	Always use the most recent GDG catalog information
infoerror infoerr eerr	S99EERR	int*	Info retrieval error code return address
infoinfo einfo	S99EINFO	int*	Info retrieval informational code return address
inforeason infocode info	S99INFO	int*	SVC 99 informational reason code return address
issuemsg sendmsg eimsg	S99EIMSG	none	Send SVC 99 messages before returning
jobsysout jbsys	S99JBSYS	none	Treat SYSOUT as normal job output
key ekey emkey	S99EKEY	int	Storage key for SVC 99 messages
mount	S99MOUNT	none	Allows mounting of volumes
msgbelow lsto	S99LSTO	none	Allocate SVC 99 messages below the 16 meg line
msgcount nmsgs enmsg nmsg	S99ENMSG	int*	Number of SVC 99 messages return address
msgerror	none	int*	Message precessing error code (returned in register 15 by IEFDB476)
msgflags msgopts eopts	S99EOPTS	int	S99RBX option bits	(2)
msgreason erco	S99ERCO	int*	Message processing reason code return address
msgseverity msglevel emsgsv msgsv emgsv	S99EMGSV	int	Minimum severity of SVC 99 messages	(3)
mustconvert oncnv	S99ONCNV	none	Use an existing allocation only if it is convertible
noconvert nocnv	S99NOCNV	none	Do not convert an existing allocation
noenq tionq	S99TIONQ	none	Do not ENQ on SYSZTIOT
nomigrate nomig	S99NOMIG	none	Do not recall migrated data sets
nomount nomnt	S99NOMNT	none	Do not mount volumes or consider offline devices
nomsg msg10	S99MSGL0	none	SVC 99 should not issue any messages
noreserve nores	S99NORES	none	Do not reserve data sets
offline offln	S99OFFLN	none	Consider offline devices
putlinerc wtorc wtprc ewrc	S99EWRC	int*	PUTLINE/WTO rewturn code return address
smsreason ersn	S99ERSN	int*	SMS reason code return address
subpool esubp emsub subp	S99ESUBP	int	Subpool number for SVC 99 message allocation
unitdevtype udevt	S99UDEVT	none	Interpret unit name as a DEVTYPE value
waitdsn wtdsn	S99WTDSN	none	Wait for data sets
waitunit wtunit wtunt	S99WTUNT	none	Wait for units
waitvol wtvol	S99WTVOL	none	Wait for volumes
wtp wto ewtp	S99EWTP	none	Send messages with WTP

In SVC 99 Request Block Keywords

• (1) in the Notes column indicates the value returned is not the value stored in S99EMSGP. osdynalloc calls IEFDB476 to turn the S99EMSGP value into an array of message buffers, a pointer to which is returned to the user in the variable specified by the keyword. Each element of the array is of type dyn_msgbuf . (This type is defined in <os.h> .) The buffer should be released by a call to free after the messages have been processed.
  If an error occurs when the library attempts to convert S99EMSGP to a message buffer array, (char *) -1 is stored in the return area. The return value from osdynalloc is not affected.

• (2) in the Notes column indicates use of these keywords is not recommended because they store an entire byte of flags. Use of the keywords for individual flags will result in more easily understandable programs. If you use one of these keywords, any flag bits turned on by previous keywords in the string will be lost. For instance, if you code the keywords nomount,flag1=0x40 , the nomount bit will not be set.

• (3) in the Notes column indicates valid values for this keyword are 0 for all messages, 4 for warning and error messages, and 8 for only error messages.

See Dynamic Allocation Keywords, Dynamic Free Keywords, Dynamic Deconcatenation Keywords, Dynamic Mark Not-in-use Keywords, Dynamic DDname Allocation Keywords, and Dynamic Allocation Inquiry Keywords for each dynamic allocation action, the supported keywords and their characteristics. For each keyword, the table shows the JCL equivalent (if any), the corresponding SVC 99 text unit key (which can be used to locate additional information about the keyword in Authorized Assembler Language Programs), the expected C type and format of the keyword value (if any), and a brief description. For keywords whose values are restricted to a specific size, char[n] is shown as the type, where n is the array size needed to hold the largest permitted value. This includes space for a terminating null so that, for instance, DDnames are shown as char[9] , even though the DDname itself is limited to eight characters. For values shown as pointers to arrays, the array passed must be of exactly the size shown.

Most options can be identified by more than one keyword. This is intended to assist you in easily locating the keywords you need. Short forms are provided which correspond to the dynamic allocation key names, as well as longer names which may be more understandable or easier to recall.

The Format column of the table may contain one or more of the following values:

Dsname	The keyword value is a data set name, and may be specified with an initial period to request that the TSO prefix or userid be prepended.
Encoded	The stored value is encoded as an integer. See the IBM documentation, the Authorized Assembler Language Programs, book for a description of the encoding for a particular keyword.
Multiple	The keyword allows more than one value to be specified.
Optional	The keyword permits a value to be specified, but one is not required.
Res Word	The keyword value is a reserved word (for example, "disp=" ) or a string of single-letter flags (for example, "recfm=" ). The permitted values are described in the IBM documentation, MVS/ESA JCL Reference.

Dynamic Allocation Keywords

Identifier	JCL Equiv	SVC 99Key	Value	Format	Description	Notes
accode acode	ACCODE=	DALACODE	char[9]		ANSI tape accessibility code
avgrec avgr	AVGREC=	DALAVGR	char*	Res Word	Average record size multiplier
blocklen blklen blkln	SPACE=(len, . . .)	DALBLKLN	int		Average block length for space allocation
blocksize blksize blksiz blksz dcbblksize dcbblksz	DCB=BLKSIZE=	DALBLKSZ	int		Maximum block size
bufalign bufaln bfaln dcbbfaln	DCB=BFALN=	DALBFALN	char*	Res Word	Buffer alignment
bufin dcbbufin	DCB=BUFIN=	DALBUFIN	int		Number of intial TCAM input buffers
bufmax bufmx dcbbufmax dcbbufmx	DCB=BUFMAX=	DALBUFMX	int		Maximum number of TCAM buffers
bufno dcbbufno	DCB=BUFNO=	DALBUFNO	int		Number of buffers to allocate
bufoff bufof dcbbufoff dcbbufof	DCB=BUFOFF=	DALBUFOF	int		ANSI tape buffer prefix offset	(1)
bufout bufou dcbbufout dcbbufou	DCB=BUFOUT=	DALBUFOU	int		Number of initial TCAM output buffers
bufsize bufsiz bufsz dcbbufsize dcbbufsz	DCB=BUFSIZE=	DALBUFSZ	int		TCAM buffer size
buftech buftek bftek dcbbftek	DCB=BFTEK	DALBFTEK	char*	Res Word	Buffering Technique
burst	BURST=	DALBURST	char*	Res Word	3800 printer burst specification
cdisp	DISP=(s,n,cd)	DALCDISP	char*	Res Word	Conditional (ABEND) disposition
chars	CHARS=	DALCHARS	char[5]		3800 printer character arrangement table
cntl	CNTL=	DALCNTL	char[27]		Reference a CNTL JCL statement
convertible convert cnvrt	none	DALCNVRT	none		Make this allocation convertible
copies copys copy	COPIES=	DALCOPYS	int		Number of SYSOUT copies
copyg	COPIES=(,(g, . . .))	DALCOPYG	int	Multiple	3800 printer copy groups
cpri dcbcpri	DCB=CPRI=	DALCPRI	char*	Res Word	TCAM relative transmission priority
cyl	SPACE=(CYL, . . .)	DALCYL	none		Allocate space in cylinders
dataclass dataclas dacl	DATACLAS=	DALDACL	char[9]		SMS data class
dcbddname dcbddn dcbdd	DCB=*.ddn	DALDCBDD	char[9]		Copy DCB information from DD statement
dcbdsname dcbdsn dcbds	DCB=dsn	DALDCBDS	char[47]	Dsname	Copy DCB information from data set
ddname ddnam ddn	none	DALDDNAM	char[9]		DDname to allocate
defer unitdefer	UNIT=(,,DEFER)	DALDEFER	none		Defer mounting until open
den dcbden	DCB=DEN=	DALDEN	char*	Res Word	Tape density
dest destnode node suser	DEST=	DALSUSER	char[9]		SYSOUT destination node
destuser userid usrid user	DEST=(n,user)	DALUSRID	char[9]		SYSOUT destination userid
diagnstrace diagnose diagns diagn dcbdiagns dcbdiagn	DCB=DIAGNS=TRACE	DALDIAGN	none		Enable diagnostic trace
dir	SPACE=(u,(p,s,d))	DALDIR	int		Number of directory blocks
disp status stats	DISP=	DALSTATS	char*	Res Word	Data set allocation status (NEW, OLD, etc.)
dsname dsnam dsn	DSN=	DALDSNAM	char[47]	Dsname	Name of data set to allocate
dsntype dsnt	DSNTYPE=	DALDSNT	char*	Res Word	Special data set type
dsorg dcbdsorg	DCB=DSORG=	DALDSORG	char*	Res Word	Data set organization
dummy	DUMMY	DALDUMMY	none		Allocate data dummy set
erropt eropt dcberropt dcberopt	DCB=EROPT=	DALEROPT	char*	Res Word	Error handling option
expiration expires labelexpdt expdt expdl	LABEL=EXPDT=	DALEXPDT DALEXPDL	char*		Expiration date	(2)
fcb fcbim	FCB=	DALFCBIM	char[5]		Printer FCB image name
fcbalign fcbverify fcbav	FCB= (,ALIGN/VERIFY)	DALFCBAV	char*	Res Word	Request FCB alignment or verification
flashcount fcnt	FLASH=(o,count)	DALFCNT	int		Number of SYSOUT copies to be flashed
flashforms flashform flash fform	FLASH=	DALFFORM	char[5]		Forms overlay name
freeclose close	FREE=CLOSE	DALCLOSE	none		Free file when closed
func dcbfunc	DCB=FUNC	DALFUNC	char*	Res Word	Card reader/punch function
gncp dcbgncp	DCB=GNCP=	DALGNCP	int		Number of channel programs for GAM
hold shold	HOLD=YES	DALSHOLD	none		Hold SYSOUT for later processing
interchange inchg	none	DALINCHG	int		Specify volume interchange media type
interval intvl dcbintvl	DCB=INTVL=	DALINTVL	int		TCAM invitation interval
ipltxtid ipltxid ipltx dcbipltxtid dcbipltxid dcbipltx	DCB=IPLTXID=	DALIPLTX	char[9]		3705 IPL text id
keylen keyln kylen dcbkeylen dcbkeyln dcbkylen	DCB=KEYLEN=	DALKYLEN	int		Key length
keyoff keyo	KEYOFF=	DALKEYO	int		VSAM key offset
labelinout labelin labelout inout	LABEL=(,,,IN/OUT)	DALINOUT	char*	Res Word	Input-only or output-only
labelpassword labelpswd paspr	LABEL=(,,pw)	DALPASPR	char*	Res Word	Password protection specification
labelseq fileseq fileno dsseq	LABEL=seq	DALDSSEQ	int		File sequence number
labeltype label	LABEL=(,lt)	DALLABEL	char*	Res Word	Type of tape label
like	LIKE=	DALLIKE	char[47]	Dsname	Name of a model data set (SMS)
limct dcblimct	DCD=LIMCT=	DALLIMCT	int		BDAM search limit
lreclk lreck dcblreclk dcblreck	DCB=LRECL=lrK	DALLRECK	none		ANSI tape LRECL is expressed in K
lrecl dcblrecl	DCB=LRECL=	DALLRECL	int		Logical record length	(3)
member membr	DSN=ds(mem)	DALMEMBR	char[9]		PDS member name
mgmtclass mgmtclas mgcl	MGMTCLAS=	DALMGCL	char[9]		SMS management class
mode dcbmode	DCB=MODE=	DALMODE	char*	Res Word	Card reader/punch mode
modify mmod	MODIFY=	DALMMOD	char[4]		3800 printer copy modification module
modifytrc mtrc	MODIFY=(,trc)	DALMTRC	int		3800 printer table reference character
ncp dcbncp	DCB=NCP=	DALNCP	int		Number of channel programs
ndisp	DISP=(s,n)	DALNDISP	char*	Res Word	Normal disposition
optcd dcboptcd	DCB=OPTCD=	DALOPTCD	char*	Res Word	Optional access method service codes
outlim outlm	OUTLIM=	DALOUTLM	int		Output limit for SYSOUT file
output outpt	OUTPUT=	DALOUTPT	char[27]		Name of OUTPUT statement
parallel unitp paral	UNIT=(,P)	DALPARAL	none		Mount volumes in parallel
password passw	none	DALPASSW	char[9]		Data set password
path	PATH=	DALPATH	char [256]		HFS path name
pathdisp pcdisp pcds cnds	PATHDISP=(n,c)	DALPCDS	char *	Res Word	Conditional (ABEND) disposition for HFS file
pathmode pmode pmde	PATHMODE=	DALPMDE	char*	Multiple Res Word	HFS file permissions
pathndisp pathdisp pndisp pnds	PATHDISP=	DALPNDS	char*	Res Word	Normal disposition for HFS file
pathopts pathopt popts popt	PATHOPTS=	DALPOPT	char*	Multiple Res Word	HFS file options
pcir dcbpcir	DCB=PCI=(r,s)	DALPCIR	char*	Res Word	PCI handling for receiving
pcis dcbpcis	DCB=PCI=(r,s)	DALPCIS	char*	Res Word	PCI handling for sending
permalloc permanent perma perm	none	DALPERMA	none		Allocate permanently
private privt	VOL=(PRIVATE,...)	DALPRIVT	none		Private volume required
protect prot	PROTECT=YES	DALPROT	none		Protect data set with RACF
prtsp dcbprtsp	DCB=PRTSP=	DALPRTSP	char*	Res Word	Printer spacing
qname	QNAME	DALQNAME	char[18]		TCAM queue name
recfm dcbrecfm	DCB=RECFM=	DALRECFM	char*	Res Word	Record format
recorg reco	RECORG=	DALRECO	char*	Res Word	Organization of VSAM file
refdd refd	REFDD=	DALREFD	char[27]		Copy DCB attributes from DDname
reserve1 reserve rsrvf dcbreserve1 dcbreserve dcbrsrvf	DCB=RESERVE= (rl,r2)	DALRSRVF	int		Number of bytes to be reserved in first buffer
reserve2 rsrvs dcbreserve2 dcbrsrvs	DCB=RESERVE= (r1,r2)	DALRSRVS	int		Number of bytes to be reserved in latter buffers
retddname rtddname retddn rtddn	none	DALRTDDN	char(*)[9]		Return DDname allocated
retdsnam rtdsname retdsn rtdsn	return DSN=	DALRTDSN	char(*)[45]		Return dsname allocated
retdsorg rtdsorg retorg rtorg	return DCB=DSORG=	DALRTORG	int*	Encoded	Return data set organization
retention labelretp retpd	LABEL=RETPD=	DALREPTD	int		Retention period
retvolume retvolser retvol rtvolume rtvolser rtvol	Return VOL=SER=	DALRTVOL	char(*)[7]		Return volume serial
secmodel secm	SECMODEL=	DALSECM	char[47]		SMS security model data set	(5)
segment segm	SEGMENT=	DALSEGM	int		SYSOUT segment page count
spaceformat spform spfrm	SPACE=(,,,form)	DALSPFRM	char*	Res Word	Format of allocated space
spacerlse release rlse	SPACE=(,,RLSE)	DALRLSE	none		Release unused space
spaceround round	SPACE=(,,,,ROUND)	DALROUND	none		Round up space request
space1 space primary prime	SPACE=(u,(s1,s2))	DALPRIME	int		Primary space allocation
space2 secondary extend secnd	SPACE=(u,(s1,s2))	DALSECND	int		Secondary space allocation
spin	SPIN=	DALSPIN	char*	Res Word	Determine when freed SYSOUT should be printed
stack dcbstack	DCB=STACK=	DALSTACK	int		Card punch stacker
storclass storclas stcl	STORCLAS=	DALSTCL	char[9]		SMS storage class
sysout sysou	SYSOUT=	DALSYSOU	char[2]		Optional Sysout class
sysoutforms sysoutformno sysoutform formno forms form sfmno	SYSOUT=(c,,f)	DALSFMNO	char[5]		SYSOUT forms number
sysoutpgmname sysoutpgmnm sysoutpgm sysoutwtr programname pgmname wtrname spgnm	SYSOUT=(c,p)	DALSPGNM	char[9]		SYSOUT writer program name
subsys ssnm	SUBSYS=	DALSSNM	char[5]		Subsystem name
subsysattr ssattr ssatt	none	DALSSAT	char*	Res Word	Subsystem attributes	(6)
subsysparm ssparm ssprm	SUBSYS= (,parm... )	DALSSPM	char[68]	Multiple	Subsystem parameters	(4)
terminal termts term	TERM=TS	DALTERM	none		Allocate TSO terminal
thresh thrsh dcbthresh dcbthrsh	DCB=THRESH	DALTHRSH	int		TCAM message queue threshhold
tracks track trk	SPACE-(TRK,. . .)	DALTRK	none		Allocate space in tracks
trtch dcbtrtch	DCB=TRTCH	DALTRTCH	char*	Res Word	Tape recording technique
ucs	UCS=	DALUCS	char[5]		SYSOUT UCS or print train
ucsfold ufold fold	UCS=(,FOLD)	DALUFOLD	none		Fold to upper case
ucsverify uverify verify uvrfy	UCS=(,,VERIFY)	DALUVRFY	none		Request UCS verification
unit	UNIT=	DALUNIT	char[8]		Unit name
volcount vlcnt	VOL=(,,,count)	DALVLCNT	int		Maximum number of volumes
volrefdsname volrefdsn vlrds	VOL=REF=	DALVLRDS	char[46]	Dsname	Request same volume as another data set
volseq vlseq	VOL=(,,seq)	DALVLSEQ	int		Sequence number of first volume to mount
volume volser vol vlser	VOL=SER=	DALVLSER	char[7]	Multiple	Names of required volumes

In Dynamic Allocation Keywords

• (1) in the Notes column indicates a value of L may be specified for this option in the keywords string. If the value is specified as an extra argument, it must be numeric. An argument value of 0x80 is interpreted as L.

• (2) in the Notes column indicates an expiration date may be specified in one of three formats. In a five-digit expiration date, the first two digits are interpreted as the years since 1900. In a seven-digit expiration date, the first four digits are the entire year. The format "yyyy/ddd", as used with the JCL EXPDT keyword, is also supported.

• (3) in the Notes column indicates a value of X may be specified for this option in the keywords string. If the value is specified as an extra argument, it must be numeric. An argument value of 0x8000 is interpreted as X.

• (4) in the Notes column indicates this parameter value is not translated to upper case.

• (5) in the Notes column indicates this keyword has the same syntax as the JCL SECMODEL keyword. That is, it may be specified either as "dsname" or as "(dsname,GENERIC)". In the latter format, the GENERIC must be present in the keyword value and cannot be specified as an extra argument. With either format, if the "?" notation is used, the extra argument may specify only the data set name. That is, the following calls are correct:

  osdynalloc(DYN_ALLOC, "secmodel=?", NULL, "SYS1.PARMLIB");
  osdynalloc(DYN_ALLOC, "secmodel=(?,GENERIC)", NULL, "SYS1.PARMLIB");

  
  while the following are not supported:

  osdynalloc(DYN_ALLOC, "secmodel=?", NULL, "(SYS1.PARMLIB,GENERIC)");
  osdynalloc(DYN_ALLOC, "secmodel=(?,?), NULL, "SYS1.PARMLIB", "GENERIC");

• (6) in the Notes column indicates the only value currently accepted for this keyword is SYSIN (requesting a SYSIN data set).

Dynamic Free Keywords

Identifier	JCL Equiv	SVC 99Key	Value	Format	Description	Notes
ddname ddnam ddn	none	DUNDDNAM	char[9]		DDname to free
dest destnode node ovsus	DEST=	DUNOVSUS	char[9]		SYSOUT destination node
destuser userid user ovuid	DEST=(n,user)	DUNOVUID	char[9]		SYSOUT destination userid
disp ndisp ovdsp	DISP=	DUNOVDSP	char*	Res Word	Disposition (KEEP, DELETE, etc)
dsn dsnam dsname	DSN=	DUNDSNAM	char[47]	Dsname	Name of data set to free
hold ovshq	HOLD=YES	DUNOVSHQ	none		Hold freed SYSOUT
member membr	DSN=ds(mem)	DUNMEMBR	char[9]		Member name to free
nohold ovsnh	HOLD=NO	DUNOVSNH	none		Do not hold freed SYSOUT
notinuse remove remov	none	DUNREMOV	none		Remove in-use even if permanently allocated
path	PATH=	DUNPATH	char[256]		HFS path name to free	(1)
pathdisp pathndisp ovpds	PATHDISP=	DUNOVPDS	char*	Res Word	Disposition of HFS file
spin	SPIN=	DUNSPIN	char*	Res Word	Print freed SYSOUT immediately
sysoutclass sysout ovcls	SYSOUT=	DUNOVCLS	char[2]		Overriding SYSOUT class
unallocate unalc	none	DUNUNALC	none		Free even if permanently allocated

In Dynamic Free Keywords

• (1) in the Notes column indicates the value for this keyword is not translated to upper case.

Dynamic Concatenation Keywords

Identifier	JCL Equiv	SVC 99Key	Value	Format	Description	Notes
ddnames ddname ddnam ddn	none	DDCDDNAM	char[9]	Multiple	DDnames to concatenate
permanent permc perm	none	DDCPERMC	none		Concatenate permanently

Dynamic Deconcatenation Keywords

Identifier	JCL Equiv	SVC 99Key	Value	Format	Description	Notes
ddname ddnam ddn	none	DDCDDNAM	char[9]		DDnames to deconcatenate

Dynamic Mark Not-in-use Keywords

Identifier	JCL Equiv	SVC 99Key	Value	Format	Description	Notes
current curnt	none	DRICURNT	none		Remove in-use for all allocations except for the current TCB
tcbaddr tcbad tcb	none	DRITCBAD	void*		Remove in-use for allocations of this TCB

Dynamic DDname Allocation Keywords

Identifier	JCL Equiv	SVC 99Key	Value	Format	Description	Notes
ddname ddnam ddn	none	DDNDDNAM	char[9]		DDnames to be allocated
retdummy rtdummy retdum rtdum	return DUMMY	DDNRTDUM	int*	Encoded	Return DUMMY status

Dynamic Allocation Inquiry Keywords

Identifier	JCL Equiv	SVC 99Key	Value	Format	Description	Notes
ddname ddnam ddn	none	DINDDNAM	char[9]		DDname for which information is needed
dsname dsnam dsn	DSN=	DINDSNAM	char[47]	Dsname	Data set for which information is needed
path	PATH=	DINPATH	char[256]		HFS file name for which information is needed	(1)
relno	none	DINRELNO	int		Relative allocation number for which information is needed
retattr rtattr rattr retatt rtatt ratt	none	DINRTATT	int*	Encoded	Return attributes of the allocation
retavgrec rtavgrec ravgrec retavgr rtavgr ravgr	return AVGREC=	DINRAVGR	int*	Encoded	Return AVGREC specification
retcdisp rtcdisp rcdisp retcdp rtcdp rcdp	return DISP=(,,c)	DINRTCDP	int*	Encoded	Return conditional disposition
retcntl rtcntl rcntl	return CNTL=	DINRCNTL	char(*)[27]		Return referenced CNTL statement
retdataclass rtdataclass rdataclass retdataclas rtdataclas rdataclas retdacl rtdacl rdacl	return DATACLAS=	DINRDACL	char(*)[9]		Return SMS data class
retddname rtddname rddname retddn rtddn rddn	none	DINRTDDN	char(*)[9]		Return DDname
retdsname rtdsname rdsname retdsn rtdsn rdsn	none	DINRTDSN	char(*)[45]		Return data set name
retdsntype rtdsntype rdsntype retdsnt rtdsnt rdsnt	return DSNTYPE=	DINRDSNT	int*	Encoded	Return data set type information
retdsorg rtdsorg rdsorg retorg rtorg rorg	return DCB=DSORG=	DINRTORG	int*	Encoded	Return data set organization
retkeyoff rtkeyoff rkeyoff retkeyo rtkeyo rkeyo	return KEYOFF=	DINRKEYO	int*		Return VSAM key offset
retlast rtlast rlast retlst rtlst rlst	none	DINRTLST	int*	Encoded	Return last allocation indication
retlike rtlike rlike	return LIKE=	DINRLIKE	char(*)[45]		Return name of model data set
retlimit rtlimit rlimit retlim rtlim rlim	none	DINRTLIM	int*		Return number of allocations over the limit
retmember rtmember rmember retmem rtmem rmem	return DSN=ds (mem)	DINRTMEM	char(*)[9]		Return member name
retmgmtclass rtmgmtclass rmgmtclass retmgmtclas rtmgmtclas rmgmtclas retmgcl rtmgcl rmgcl	return MGMTCLAS=	DINRMGCL	char(*)[9]		Return SAS management class
retndisp rtndisp rndisp retndp rtndp rndp	return DISP=(,n)	DINRTNDP	int*	Encoded	Return normal disposition
retpathcdisp rtpathcdisp rpathcdisp retpcdisp rtpcdisp rpcdisp retpcds rtpcds rpcds retcnds rtcnds rcnds	return PATHDISP=(n,c)	DINRCNDS	int*	Encoded	Return HFS file conditional disposition
retpathmode rtpathmode rpathmode retpmode rtpmode rpmode retpmde rtpmde rpmde	return PATHMODE=	DINRPMDE	int*	Encoded	Return HFS file permissions
retpathopts rtpathopts rpathopts retpathopt rtpathopt rpathopt retpopts rtpopts rpopts retpopt rtpopt rpopt	return PATHOPTS=	DINRPOPT	int*	Encoded	Return HFS file options
retrecorg rtrecorg rrecorg retreco rtreco rreco	return RECORG=	DINRRECO	int*	Encoded	Return VSAM file organization
retrefdd rtrefdd rrefdd retrefd rtrefd rrefd	return REFDD=	DINRREFD	char(*)[27]		Return REFDD DDname
retsecmodel rtsecmodel rsecmodel retsecm rtsecm rsecm	return SECMODEL=	DINRSECM	struct*		Return SMS security model information	(2)
retsegment rtsegment rsegment retsegm rtsegm rsegm	return SEGMENT=	DINRSEGM	int*		Return SYSOUT segment page count
retspin rtspin rspin	return SPIN=	DINRSPIN	int*	Encoded	Return allocation SPIN specification
retstatus rtstatus rstatus retsta rtsta rsta	return DISP=stat	DINRTSTA	int*	Encoded	Return allocation status
retstorclass rtstorclass rstorclass retstorclas rtstorclas rstorclas retstcl rtstcl rstcl	return STORCLAS	DINRSTCL	char(*)[9]		Return SMS storage class
rettype rttype rtype rettyp rttyp rtyp	return DUMMY/*/SYSOUT/TERM	DINRTTYP	int*	Encoded	Return special allocation type information

In Dynamic Allocation Inquiry Keywords

• (1) in the Notes column indicates the value for this keyword is not translated to upper case.

• (2) in the Notes column indicates the value for the "retsecmodel" keyword is a pointer to an object of type struct secmodel , defined in <os.h> . This structure includes a field profile , in which the model profile name will be stored, and a field generic , in which an encoded indication of whether the profile is generic will be stored. See the IBM publication, the Authorized Assembler Language Programs for encoding information.

EXAMPLE

This example uses the inquiry function of SVC 99 to determine the name of the file allocated to the DDname SYSIN. It then derives the name of an object data set from the returned name, and allocates that name to the DDname SYSLIN.

#include <os.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

main() {
   char dsname[45];
   char member[9];
   char keywords[100];
   char pathname[256];
   int reason = 0;
   int rc;

   rc = osdynalloc(DYN_INQUIRE,
                   "ddn=sysin,retdsn=?,retmem=?,retpath=?,reason=?",
                   NULL, dsname, member, pathname, &reason);
   if (rc < 0) abort();         /* if input parm error */
   if (rc != 0) {
      if (reason == 0x0438)     /* DDname not found */
         printf("SYSIN is not allocated.\n");
      else printf("osdynalloc inquiry failed, rc = %d, "
                  "reason = %04x\n",
                  rc, reason);
      exit(EXIT_FAILURE);
   }

   if (dsname[0] != 0) { /* the file is a data set */
      int l = strlen(dsname);
      char *lastdot;
      if (l > 4 && memcmp(dsname+l-4, ".OBJ", 4) == 0) {
         printf("SYSIN appears to be a .OBJ dataset.\n");
         exit(EXIT_FAILURE);
      }
      lastdot = strrchr(dsname, '.');   /* find final qualifier */
      if (!lastdot) lastdot = dsname+strlen(dsname);
      if (lastdot+4 > &dsname[44]) {
         printf("Object data set name too long.\n");
         exit(EXIT_FAILURE);
      }
      strcpy(lastdot, ".OBJ");          /* replace with .OBJ */
      sprintf(keywords,
              "ddn=sysin,dsn=%s%s%s,disp=shr,reason=?",
              dsname, (member[0]? ",member=": ""), member);
                                  /* build keywords, with or without
                                     a member name */
      rc = osdynalloc(DYN_ALLOC, keywords, NULL, &reason);
      if (rc < 0) abort();
      if (rc != 0) {
         printf("osdynalloc dsn allocation failed, rc = %d, "
                "reason = %04x\n",
                rc, reason);
         exit(EXIT_FAILURE);
      }
   } else {      /* else, an HFS path name */
      int l = strlen(pathname);
      char *lastdot;
      if (l > 2 && memcmp(pathname+l-2, ".o", 2) == 0) {
         printf("SYSIN appears to be a .o HFS file.\n");
         exit(EXIT_FAILURE);
      }
      lastdot = strrchr(pathname, '.');   /* find extension */
      if (!lastdot) lastdot = pathname+strlen(pathname);
      if (lastdot+2 > &pathname[255]) {
         printf("Object data set name too long.\n");
         exit(EXIT_FAILURE);
      }
      strcpy(lastdot, ".o");            /* replace with .o */
      rc = osdynalloc(DYN_ALLOC,
                      "ddn=syslin,path=?,pathdisp=keep,"
                      "pathopts=ordonly,reason=?", NULL,
                      pathname, &reason);
      if (rc < 0) abort();
      if (rc != 0) {
         printf("osdynalloc path allocation failed, rc = %d, '
                "reason = %04x\n",
                rc, reason);
         exit(EXIT_FAILURE);
      }
   }

   puts("SYSLIN successfully allocated.");
   exit(EXIT_SUCCESS);
}

Chapter Contents

Previous

Next

Top of Page

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.