dynalloc() — Allocate a data set

Standards

Format

#include <dynit.h>

int dynalloc(__dyn_t *dyn_parms);

General description

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.

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.

Returned value

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.

Example

/* 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);
   }
}

Related information

• dynit.h — Dynamic allocation routines
• dynfree() — Deallocate a data set
• dyninit() — Initialize __dyn_t structure
• svc99() — Access supervisor call