Standards / Extensions | C or C++ | Dependencies |
---|---|---|
C Library | both |
#include <dynit.h>
int dynalloc(__dyn_t *dyn_parms);
The dynalloc() function dynamically allocates a MVS data set using the MVS SVC 99 service and by building an SVC 99 parameter list based on parameters specified in dyn_parms. The dynalloc() function corresponds to verb code 1 for SVC 99. To use other SVC 99 verb codes, see svc99() — Access supervisor call.
To avoid infringing on the user's name space, this nonstandard function has two names. One name is prefixed with two underscore characters, and one name is not. The name without the prefix underscore characters is exposed only when you use LANGLVL(EXTENDED).
To use this function, you must either invoke the function using its external entry point name (that is, the name that begins with two underscore characters), or compile your application with LANGLVL(EXTENDED). When you use LANGLVL(EXTENDED). any relevant information in the header is also exposed.
The request block extension and the error message parameter list can be used to process the messages returned by SVC99 when an error occurs. To use this feature you must allocate and initialize these structures using the processes described in z/OS MVS Programming: Authorized Assembler Services Guide. You must also make them available to the dynalloc() function by assigning their addresses to __rbx or __emsgparmlist.
Because additional fields have been added to the __dyn_t structure, you should recompile existing source code with the latest dynit.h header file to access the new fields.
Some values, such as ddname and dsname, will be converted to uppercase internally when they are used by the dynalloc() function.
Element | Text Unit Key | Text Unit Value | Type | Description |
---|---|---|---|---|
__ddname | DALDDNAM | 0001 | char * | ddname (maximum length of 8)1. If 8 question marks (????????) are specified, it means that the request expects a system-generated ddname returned. |
__dsname | DALDSNAM | 0002 | char * | Fully qualified data-set name (maximum length of 44)1. |
__sysout | DALSYSOU | 0018 | char | The class of the system output data set (for example, SYSOUT=A). Values are: alphabetic character, or the macro __DEF_CLASS, to specify the default class. |
__sysoutname | DALSPGNM | 0019 | char * | Program name for sysout. The __sysout field must be specified with this field (maximum length of 8)1. |
__member | DALMEMBR | 0003 | char * | Member of a partitioned data set to be allocated (maximum length of 8)1. |
__status | DALSTATS | 0004 | char | Data set status. Values are: __DISP_OLD, __DISP_NEW, __DISP_MOD, and __DISP_SHR, which are defined in dynit.h. |
__normdisp | DALNDISP | 0005 | char | Specifies the normal disposition of a data set. Values are: __DISP_CATLG, __DISP_UNCATLG, __DISP_DELETE, and __DISP_KEEP, which are defined in dynit.h. |
__conddisp | DALCDISP | 0006 | char | Specifies the conditional disposition of a data set. Values are: __DISP_CATLG, __DISP_UNCATLG, __DISP_DELETE, and __DISP_KEEP, which are defined in dynit.h. |
__unit | DALUNIT | 0015 | char * | Unit name of the device that the data set will (or does, if it already exists) reside on (maximum length of 8)1. |
__volser | DALVLSER | 0010 | char * | Volume serial number of the device a data set will (or does, if it already exists) reside on (maximum length of 6)1. |
__dsorg | DALDSORG | 003C | char | Data set organization of a data set. Values are:
|
__alcunit | DALCYL, DALTRK | 0008, 0007 | char | Unit of space allocation for a data set. Values are: __CYL and __TRK. To specify allocation units in blocks, use the field __avgblk. |
__primary | DALPRIME | 000A | int | Primary space allocation for a data set. |
__secondary | DALSECND | 000B | int | Secondary space allocation for a data set. |
__dirblk | DALDIR | 000C | int | Number of directory blocks for a partitioned data set. |
__avgblk | DALBLKLN | 0009 | int | Specifies the unit of space allocation to be blocks and sets the average block length. |
__recfm | 0049 | short | Record format of a data set. The following macros in dynit.h
can be added together to determine the __recfm value:
For example, to specify a recfm of FBA, set: _recfm = _FB_ + _A_ |
|
__blksize | DALBLKSZ | 0030 | short | Block size of a data set. |
__lrecl | DALLRECL | 0042 | unsigned short | Record length of a data set. |
__volrefds | DALLVLRDS | 0014 | char * | Fully qualified name of a cataloged data set to be used as a model for obtaining volume serial information (maximum length of 44)1. |
__dcbrefds | DALDCBDS | 002C | char * | Fully qualified name of a cataloged data set to be used as a model for obtaining DCB information (maximum length of 44)1. |
__dcbrefdd | DALLDCBDD | 002D | char * | ddname of a data set to be used as a model for obtaining DCB information (maximum length of 9)1. For more information, see z/OS MVS Programming: Authorized Assembler Services Guide. |
__misc_flags | unsigned char | Specifies the attributes. See Example for instructions on how to specify the flags shown below using a logical | (OR). | ||
__CLOSE | DALCLOSE | 001C | unsigned char | (Flag) Deallocate data set when file is closed. |
__RELEASE | DALRLSE | 000D | unsigned char | (Flag) Release unused space when file is closed. |
__CONTIG | DALSPRFRM | 000E | unsigned char | (Flag) Allocate space contiguously. |
__ROUND | DALROUND | 000F | unsigned char | (Flag) Allocate space in whole cylinders when blocks are requested. |
__TERM | DALTERM | 0028 | unsigned char | (Flag) Time-sharing terminal is to be used as I/O device. |
__DUMMY_DSN | DALDUMMY | 0024 | unsigned char | (Flag) Dummy data set is to be allocated. |
__HOLDQ | DALSHOLD | 0059 | unsigned char | (Flag) Hold queue routing for sysout data set. |
__PERM | DALPERMA | 0052 | unsigned char | (Flag) Set permanent allocation attribute. |
__password | DALPASSW | 0050 | char * | Password for a password-protected data set. The dsname field must be specified with this field (maximum length of 8)1. |
__miscitems | char * __ptr32 * __ptr32 | For all other text unit keys not available in __dyn_t, this pointer will let you specify an array of text unit strings. If you specify this field, you must turn the high bit on the last item (as in svc99()). Use the bitwise inclusive-OR (|) operand with the last item and the hexadecimal value 0x80000000. | ||
__infocode | short | Returns the information code returned by the MVS dynamic allocation functions. For more information, see z/OS MVS Programming: Authorized Assembler Services Guide. | ||
__errcode | short | Returns the error code returned by the MVS dynamic allocation functions. For more information, see z/OS MVS Programming: Authorized Assembler Services Guide. | ||
__storclass | DALSTCL | 8004 | char * | Specifies the storage class of system managed storage. |
__mgntclass | DALMGCL | 8005 | char * | Specifies the management class of a data set. |
__dataclass | DALDACL | 8006 | char * | Specifies the data class of a data set. |
__recorg | DALRECO | 800B | char | Specifies the record organization of a VSAM data set. Values are: __KS, __ES, __RR, __LS. |
__keyoffset | DALKEYO | 800C | short | Specifies the key offset. The position of the first byte of the key in records of the specified VSAM data set. |
__keylength | DALKYLEN | 0040 | short | Specifies the length in bytes of the keys used in the data set. |
__refdd | DALREFD | 800D | char * | Specifies the name of the JCL DD statement from which the attributes are to be copied. For more information, see z/OS MVS Programming: Authorized Assembler Services Guide. |
__like | DALLIKE | 800F | char * | Specifies the name of the model data set from which the attributes are to be copied. |
__dsntype | DALDSNT | 8012 | char | Specifies the type attributes of a data set. Valid types include __DSNT_BASIC, __DSNT_EXTPREF, __DSNT_EXTREQ, __DSNT_HFS, __DSNT_LARGE, __DSNT_LIBRARY, __DSNT_PDS, and __DSNT_PIPE. |
__pathname | DALPATH | 8017 | char * | Pathname (maximum length is 255)1. See z/OS UNIX System Services User's Guide for the pathname format. |
__pathopts | DALPOPT | 8018 | int | Specifies file options for the HFS file. Values are: __PATH_OCREAT, __PATH_OAPPEND, __PATH_OEXCL, __PATH_ONOCTTY, __PATH_OTRUNC, __PATH_ONONBLOCK, __PATH_ORDONLY, __PATH_OWRONLY, __PATH_ORDWR. For information about the file options, see z/OS MVS JCL Reference. For information about DYNALLOC, see z/OS MVS Programming: Authorized Assembler Services Guide. |
__pathmode | DALPMDE | 8019 | int | Specifies the file access attributes for the HFS file. Values are: __PATH_SIRUSR, __PATH_SIWUSR, __PATH_SIXUSR, __PATH_SIRWXU, __PATH_SIRGRP, __PATH_SIWGRP, __PATH_SIXGRP, __PATH_SIRWXG, __PATH_SIROTH, __PATH_SIWOTH, __PATH_SIXOTH, __PATH_SIRWXO, __PATH_SISUID, __PATH_SISGID. For information on the file attributes, refer to z/OS MVS JCL Reference. For information on DYNALLOC, refer to z/OS MVS Programming: Authorized Assembler Services Guide. |
__pathndisp | DALPNDS | 801A | char | Specifies the normal HFS file disposition desired. It is either __DISP_KEEP or __DISP_DELETE |
__pathcdisp | DALPCDS | 801B | char | Specifies the abnormal HFS file disposition desired. It is either __DISP_KEEP or __DISP_DELETE |
__rbx | __S99rbx_t * __ptr32 | For users who make use of the Request Block Extension. | ||
__emsgparmlist | __S99emparms_t * __ptr32 | For users who want to process associated messages with the dynamic allocation. | ||
__rls | DALRLS | 801C | char | Specifies the type of record level sharing (RLS) being done for a specific data set. The valid values are __RLS_NRI, __RLS_CR and __RLS_CRE. See z/OS XL C/C++ Programming Guide and z/OS DFSMS Using Data Sets for a description of these VSAM RLS/TVS access modes. |
1 If an element exceeds its maximum allowable length, it is truncated to that length. |
Special behavior for POSIX C: For POSIX C programs, allocations established by the dynalloc() function persist neither after an exec nor in the child process after fork().
Special behavior for enhanced ASCII: When compiled ASCII, there is one input element in the __dyn_t structure that must contain EBCDIC text strings and there is a consideration to note with respect to retrieval of error messages related to a dynamic allocation failure. On input, any character data provided in __miscitems must be specified in the EBCDIC codeset. The __dynalloc() function does not decode the text units and convert the character data. The text units are passed directly to the system. When __emsgparmlist is specified, indicating intent to retrieve error messages using the IEFDB476 service, it should be noted that all error messages returned by the service will be in the EBCDIC codeset.
Special behavior for AMODE 64: The definitions in the __dyn_t structure are changed to require three of its pointer elements to be 32 bits wide. This is because the system services that work with these control structures require 31-bit addressable storage. The __miscitems are additional text units that are not already supported by elements of the __dyn_t structure. These are propagated by the dynalloc() function directly to into an SVC 99 call. The __rbx is propagated by the dynalloc() function directly into an SVC 99 call. The __emsgparmlist address is designed to be passed as a parameter to the IEFDB476 service, which is an AMODE 31 service, to retrieve messages associated with a dynamic allocation failure. The __dyn_t structure itself can be in 64-bit addressable storage. The __dyn_t structure must be initialized using the dyninit() macro defined in dyninit.h to ensure the proper "hidden" version indicator is used. Improper initialization of the __dyn_t structure will result in undefined behavior.
If successful under MVS, the dynalloc() function returns 0.
If SVC 99 is not supported on your system, or if a text string passed to SVC 99 cannot be built from a field in dyn_parms, a negative value is returned.
The value -1 is returned if there is not sufficient storage to process all the text units. Otherwise, the return code is the value returned from SVC 99, and the error and information codes are found in those fields in dyn_parms.
For example, if you pass NULL to the dynalloc() function, the return code is nonzero.
For more information about return codes, see z/OS MVS Programming: Authorized Assembler Services Guide.
⁄* CELEBD07
This example dynamically allocates a data set.
*⁄
#include <dynit.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#define ZERO 0
int main () {
__dyn_t ip;
dyninit(&ip);
ip.__ddname = "mydd"; ⁄* MYDD DD *⁄
ip.__dsname = "PLIXXX.MY.DATASET"; ⁄* DSN='PLIXXX.MY.DATASET' *⁄
ip.__status = __DISP_NEW; ⁄* DISP=(NEW,CATLG) *⁄
ip.__normdisp = __DISP_CATLG;
ip.__alcunit = __CYL; ⁄* SPACE=(CYL,(2,1)), *⁄
ip.__primary = 2;
ip.__secondary = 1;
ip.__dirblk = 1;
ip.__misc_flags = __RELEASE & __CONTIG; ⁄* RLSE,CONTIG) *⁄
ip.__dsorg = __DSORG_PO; ⁄* DCB=(DSORG=PO, *⁄
ip.__recfm = _F_ + _B_ + _A_; ⁄* RECFM=FBA, *⁄
ip.__lrecl = 121; ⁄* LRECL=121, *⁄
ip.__blksize = 12100; ⁄* BLKSIZE=12100) *⁄
if (dynalloc(&ip) != ZERO)
{
printf("Dynalloc failed with error code %d, info code %d\n",
ip.__errcode, ip.__infocode);
}
}