Table Of Contents
Parent Topic
Next Topic

High-Level Language SWSALLOC (SWCPAL) Function

Related Topics

Web Server API Function Index

	May be used in Shadow/REXX
	May be used from Other REXX interpreters
	HLL entry point name is SWCPAL

SWSALLOC is the Web Server API function used to dynamically allocate an MVS dataset for use by Web Client program.

The format of this command is similar in features and functions to the TSO/E Allocate command. A text string is used as input in order to provide the parameters necessary to allocate the specified dataset. Use the SWSFREE command to de-allocate datasets allocated with the SWSALLOC command.

SWCPAL Call Arguments

The SWSALLOC (SWCPAL) function arguments are described in the table which follows. Only two of the three arguments are required.

Arg. No.	HLL Argument Type			I/O	Description of Argument
Arg. No.	C	COBOL	PL/I	I/O	Description of Argument
1	LONG	PIC S9(5) COMP	FIXED BIN(31)	Input	The length of the allocation command string. If the length is longer than the actual command, trailing nulls or blanks will be ignored. If the length is less than the actual command string, the allocation command string will be truncated and possibly cause execution errors. The maximum string length is 32768 bytes.
2	CHAR *	PIC X(nnnnn)	CHAR(nnnnn)	Input	The allocation command string. See Supported Dynamic Allocation Keywords below.
3	SWSASB *	Usage pointer	PTR	Output	The Shadow OS/390 Web Server Allocation Status Block. This is an optional argument that provides information concerning the status of the allocation request. If you do not specify this argument, you will not have access to the reason code nor the DAIR code.

Return Values

SWSALLOC always sets a signed numeric return code value. Possible values are:

SWS_SUCCESS: The operation succeeded. The specified operation was performed.
SWS_ERROR: A parameter validation or run-time error was encountered. Error information is available using the SWSERROR function.
SWS_ENVIRONMENT_ERROR: The request can not be processed because of a run-time environmental error. For example, you invoked the API service outside of a Web transaction procedure or from outside the server's address space. Use the server's wrap-around trace to obtain diagnostic information.
Any other value: The operation failed. Generally this indicates that the file was not allocated. There will be an error message in the Allocation Status Block describing the error.
Top

Supported Dynamic Allocation Keywords

The SWSALLOC (SWCPAL) interface supports the following dataset allocation request parameters:

DSN(DSNAME)	Specifies the name of the dataset to be allocated. You may only specify a single dataset name. Dataset names must be fully qualified as there will be no prefix appended to the supplied name. Note: This is a required parameter unless you specify a PATH parameter.
DDN(DDNAME)	Specifies the DDNAME to associate with the allocated file. If you do not specify one, one will be dynamically generated for you. The generated DDNAME may be obtained from the Allocation Status Block which is input to the allocation request.
DEST(DESTINATION/NODE USERID)	Remote destination or a User at a specified node to which SYSOUT data sets are to be routed.
DISP(STATUS NORMAL ABNORMAL)	Specifies the disposition of file upon normal and abnormal (conditional) session termination. Status disposition: Indicates the disposition of the file upon normal session termination. SHR = Dataset exists and exclusive control is not required OLD = Dataset exists and exclusive control is required MOD = Additions are to be made to the dataset NEW = Dataset is to be created Normal termination disposition: Indicates the disposition of the file upon normal session termination. UNCATALOG = Specifies that the file should be uncatalogued CATALOG = Specifies that the file should be catalog KEEP = Specifies that the file should be kept. DELETE = Specifies that the file should be deleted. Abnormal (conditional) termination disposition: indicates the disposition of the file upon abnormal (conditional) session termination. UNCATALOG = Specifies that the file should be uncatalogued CATALOG = Specifies that the file should be catalog KEEP = Specifies that the file should be kept. DELETE = Specifies that the file should be deleted.
SYSOUT(CLASS)	Dataset is to be a system output dataset
VOLUME(SERIAL(s))	Volume(s) on which the dataset resides or is to reside.
BLKSIZE(VALUE)	Blocksize Must be 0 to 32760
BLOCKS(PRIMARY SECONDARY)	Space is to be allocated by BLOCKS Note: Requires the BLKSIZE parameter.
TRACKS(PRIMARY SECONDARY)	Space is to be allocated by tracks
CYLINDERS(PRIMARY SECONDARY)	Space is to be allocated by cylinders
DIR(INTEGER)	Number of Directory Blocks required
LIKE(MODEL_DATASET_NAME)	The model dataset is a dataset whose attributes are to be used to allocate a new dataset. The following attributes are copied from the model dataset: Primary and Secondary space quantities (SPACE) Directory space quantity (DIR) Dataset Organization (DSORG) Record Format (RECFM) Optional Services Codes (OPTCD) Logical Record Length (LRECL) Key Length (KEYLEN) Blocksize (BLKSIZE) Volume Sequence Number (VSEQ) Expiration Date (EXPDT) If SMS is active the following attributes are not copied: Optional Services Codes (OPTCD) Blocksize (BLKSIZE) Volume Sequence Number (VSEQ) Expiration Date (EXPDT) Any attribute(s) of the model data set can be overridden by explicitly specifying the appropriate keyword(s) on the allocate command.
HOLD	Dataset is to be placed on a hold queue upon de-allocation
UNIT(UNIT_TYPE)	Device type to which a file or data set is to be allocated.
UCOUNT(COUNT)	Maximum number of devices to which a file or data set may be allocated.
PARALLEL	One device mounted for each volume specified on the volume parameter
MAXVOL(VOL_COUNT)	Maximum number of volumes a data set may use
PRIVATE	A volume which is not permanently resident or reserved is to be assigned the private volume use attribute.
RELEASE	Unused space is to be deleted when the data set is closed.
VSEQ(VOL_SEQ_NUM)	Which volume of a multi-volume data set to begin processing with.
ROUND	Allocated space should be equal to one or more cylinders.
BFALN(VALUE)	Buffer boundary alignment Legitimate values are: D = Double word boundary F = Full word boundary
BFTEK(VALUE)	Type of buffering Legitimate values are: A = Automatic record area construction D = Dynamic buffering E = Exchange buffering R = Record buffering S = Simple buffering
BUFL(INTEGER)	Buffer length Must be 0 to 32760
BUFNO(INTEGER)	Number of buffers Must be 0 to 255
BUFOFF(INTEGER)	Block prefix length Must be 0 to 99
DSORG(VALUE)	Dataset Organization Legitimate values are: DA = Direct Access DAU = Direct Access Unmovable PO = Partitioned Organization POU = Partitioned Organization Unmovable PS = Physical Sequential PSU = Physical Sequential Unmovable
EROPT(VALUE)	Error Option Legitimate values are: ABE = Abnormal End-Of-Task ACC = Accept block causing error SKP = Skip block causing error
KEYLEN(INTEGER)	Key length Must be 0 to 255
LIMCT(INTEGER)	Number of blocks or tracks to be searched for a block or available space Must be 0 to 32760
LRECL(VALUE)	Logical Record Length Legitimate values are: 0 to 32760 Character "X" 1 to 16384 with K-multiplier Where: X = LRECL value exceeds 32756 for variable length spanned records processed under QSAM K = LRECL value is a multiplier of 1024
NCP(INTEGER)	Maximum number of read or write macros before a check Must be 0 to 255 If you are running TSO/E on MVS/ESA SP 4.2.2 or earlier, the maximum value is 99.
OPTCD(VALUE)	Optional Services Codes Legitimate values are: A = Actual device addresses presented in read and write macro instructions B = End-Of-File recognition disregarded for tapes C = Chained scheduling is to be used E = Extended search for block or available space F = Feedback may be requested in read and write macro instructions Q = ANSI translate R = Requests relative block addressing T = Requests user totaling facility W = Requests a validity check for write operations on direct access devices J = Indicates that the character after the carriage control character is to be interpreted as a table reference character
PROCOPT(VALUE)	File processing option Legitimate values are: INPUT = Specifies that the data set is to be processed for input only OUTPUT = Specifies that the data set is to be processed for output only
EXPDT(VALUE)	Dataset expiration date (YYDDD OR YYYY/DDD)
RETPD(INTEGER)	Dataset retention period (NNNN)
FCB(IMAGE_ID)	Forms Control Image (Buffer) to be used to print an output data set. IMAGE_ID specifies a 1 to 4 alphanumeric or national characters which identify the image to be loaded into the Forms Control Buffer.
COPIES(NNN)	Number of copies of a dataset to print. An integer from 1 to 255.
COPYGROUPS(GROUP_VALUE1 GROUP_VALUE2 ...GROUP_VALUE8))	Used with the COPIES option to specify the number of times each page is to be printed. Up to eight group values may be specified with a sum not exceeding the number specified in the COPIES parameter.
PROTECT	Specifies that the DASD data set or tape volume containing a tape data set is to be RACF protected.
ACCODE(VALUE)	ANSI accessibility code (A through Z).
OUTBIN(VALUE)	Specifies the output bin on the IBM 3800 laser printer. Legitimate values are: BURST = Specifies that the data set should be sent to the burster/trimmer bin on the IBM 3800 laser printer. NOBURST = Specifies that the data set should be sent to the continuous feed bin on the IBM 3800 laser printer.
CHARS(CHAR_TABLE1 ...CHAR_TABLE4)	Specifies the character table that is to be used for printing. 1 to 4 character tables may be specified.
FLASH(NAME COPIES)	Provides the ability to print a form, grid, design, or constant data on paper as it is is being processed through the 3800 printer. Legitimate values are: NAME - Specifies the name of the forms overlay to be used. COPIES - Specifies the number of copies on which the forms overlay is to be used. Note: Separate parameters by spaces. Do not use commas.
FORMS(VALUE)	Specifies the specific print form to be mounted.
OUTDES(OUTPUT_DESCRIPTOR_NAME ...)	Specifies a list of output descriptors that will be associated with the sysout data set. These descriptors are created by //OUTPUT JCL statements in the Shadow OS/390 Web Server or Shadow Direct procedure. Note: Separate parameters by spaces. Do not use commas.
UCS(UCS_NAME)	Specifies the universal character set (font name) to be used when processing a print data set in the absence of a 'CHARS' specification.
WRITER(EXTERNAL_WRITER_NAME)	Specifies the member name of a program in the system library that is to write the sysout data set. This program will be used instead of JES2 or JES3.
STORCLAS(STORAGE_CLASS)	The name of the storage class which is used to specify the service level for the data set.
MGMTCLAS(MANAGEMENT_CLASS)	The management class which is used to specify management criteria for the data set.
DATACLAS(DATA_CLASS)	The name of the data class which is used as an allocation template for the data set.
RECFM(OPTION1 OPTION2 ...OPTION5)	Record Format Legitimate option values are: A = ASA PRINTER CHARACTERS B = BLOCKED D = VARIABLE LENGTH ASCII RECORDS F = FIXED M = MACHINE CONTROL CHARACTER S = STANDARD BLOCKS OR SPANNED T = TRACK OVERFLOW U = UNDEFINED V = VARIABLE Note: Combinations of these options may be selected. Each selection must be separated by a space. Review your MVS JCL Reference Manual for legitimate combinations.
RECORG(ORGANIZATION)	Dataset Organization Legitimate values are: KS = VSAM Cluster (KSDS) ES = VSAM Entry Sequenced (ESDS) RR = VSAM Relative Record (RRDS) LS = VSAM Linear Space (LDS)
KEYOFF(OFFSET)	Key Offset.
REFDD(DDNAME)	The DDNAME of a data set whose properties specified on the JCL statement and in the data class are to be used to allocate the new data set. The following properties are copied from the referenced DD statement: Dataset Organization (RECORG) Size Directory blocks Logical Record Length (LRECL) Record Format (RECFM) Key Length (KEYLEN) Key Offset (KEYOFF)
SECMODEL(MODEL_NAME)	The name of a "model" profile which RACF should use in creating a discrete profile for the data set.
DSNTYPE(DSNTYPE)	DATA SET NAME TYPE Legitimate values are: LIBRARY = A partitioned data set in PDSE format PDS = A partitioned data set in record format PIPE = A data pipe HFS = An HFS (Hierarchical File System) file
RLS(RLS_VALUE)	Record Level Sharing Legitimate values are: CR = Consistent Read NRI = No Read Integrity
FILEDATA(VALUE)	How the system converts between record format and byte-stream format. Currently meaningful only if path also is coded and the program uses BSAM or QSAM. Legitimate values are: TEXT = Data consists of records that are separated by a delimiter. Currently it is EBCDIC newline (x'15'). BINARY = Data does not contain record delimiters. In the current release the default is binary when creating the file. If you do not code PATHOPTS(OCREATE), then FILEDATA temporarily overrides the creation value.
PATH(PATHNAME)	Identifies an HFS file. A pathname consists of the names of the directories from the root to the file being identified, and then the name of the file. The form is /NAME1/NAME2/.../NAMEn. A pathname begins with a slash (/). The system treats any consecutive slashes like a single slash. The pathname can be 1 to 250 characters. A name can be 1 to 249 characters. Consists of printable characters from x'40' through x'FE'. A pathname is case sensitive. Thus, /usr/joe and /USR/joe define two different files. Note: This is a required parameter unless you specify a DSN parameter.
PATHDISP(NORMAL ABNORMAL)	Specifies the disposition of an HFS file upon normal and abnormal (conditional) session termination. Normal termination disposition: Indicates the disposition of the HFS file upon normal session termination. KEEP = Specifies that the file should be kept. DELETE = Specifies that the file should be deleted. Abnormal (conditional) termination disposition: indicates the disposition of the HFS file upon abnormal (conditional) session termination. KEEP = Specifies that the file should be kept. DELETE = Specifies that the file should be deleted. Note: The default for datasets allocated with the PATH parameter is PATHDISP(KEEP KEEP).
PATHMODE(FILE_ACCESS_ATTRIBUTE ...)	Specifies the file access attributes when the PATHOPTS operand specifies OCREAT. A FILE_ACCESS_ATTRIBUTE is one of the following: SIRUSR SIWUSR SIXUSR SIRWXU SIRGRP SIWGRP SIXGRP SIRWXG SIROTH SIWOTH SIXOTH SIRWXO SISUID SISGID You may specify up to 14 FILE_ACCESS_ATTRIBUTES. The system treats duplicate specifications of FILE_ACCESS_ATTRIBUTES as a single specification.
PATHOPTS(FILE_OPTION ...)	Specifies the file access and status used when accessing a file specified on the path operand. A FILE_OPTION can be in the access group or the status group and is one of the following: Valid Access Groups are: ORDONLY OWRONLY ORDWR Valid Status Groups are: OAPPEND OCREAT OEXCL ONOCTTY ONONBLOCK OSYNC OTRUNC You can specify up to 8 FILE_OPTIONs. The system treats duplicate specifications of FILE_OPTIONs as a single specification. Code the FILE_OPTIONs as follows. Specify only one FILE_OPTION from the access group. if you specify more than one access group file-option, the system ignores them and uses ORDWR as the option. Specify up to 7 FILE_OPTIONs from the status group. You may specify any combination of FILE_OPTIONs from the status group.
SEGMENT(INTEGER)	The number of pages produced for a sysout data set before they are processed for printing. Must be 1 to 99999
SPIN(VALUE)	Specifies when a sysout data set is printed. Legitimate values are: UNALLOC = Makes the dataset available for printing immediately after the dataset is unallocated from an explicit unallocation or at the end of the session. NO = Makes the dataset available for printing at the end of the session.
MESSAGE(VALUE)	Specifies whether or not to display dynamic allocation failure messages on the system console. This value overrides the user-specifiable system default (See FILEMESSAGES). Legitimate values are: YES = Display dynamic allocation failure messages NO = Do not display dynamic allocation failure messages
MOUNT(VALUE)	Specifies whether to allow or not allow a volume to be mounted in order to satisfy a dynamic allocation request. This value overrides the user-specifiable system default. (See FILEMOUNT) Legitimate values are: YES = Allow the system to mount a volume to satisfy a dynamic allocation request. NO = Do not allow the system to mount a volume to satisfy a dynamic allocation request.
RECALL(VALUE)	Specifies whether to allow or not allow the system to recall a migrated dataset in order to satisfy a dynamic allocation request. This value overrides the user-specifiable system default. (See FILERECALL) Legitimate values are: YES = Allow the system to recall datasets to satisfy a dynamic allocation request. NO = Do not allow the system to recall datasets to satisfy a dynamic allocation request.

Top

File Access Attributes for PATHMODE parameter

Sub-Parameter	Definition
SIRUSR	Specifies permission for the file owner to read the file.
SIWUSR	Specifies permission for the file owner to write the file.
SIXUSR	Specifies permission for the file owner to search, if the file is a directory, or to execute, for any other file.
SIRWXU	Specifies permission for the file owner to read, write, and search, if the file is a directory, or to read, write, and execute, for any other file. this value is the bit inclusive or of SIRUSR, SIWUSR, and SIXUSR.
SIRGRP	Specifies permission for users in the file group to read the file.
SIWGRP	Specifies permission for users in the file group to write the file.
SIXGRP	Specifies permission for users in the file group to search, if the file is a directory, or to execute, for any other file.
SIRWXG	Specifies permission for users in the file group to read, write, and search, if the file is a directory, or to read, write, and execute, for any other file. This value is the bit inclusive or of SIRGRP, SIWGRP, and SIXGRP.
SIROTH	Specifies permission for users in the file other class to read the file.
SIWOTH	Specifies permission for users in the file other class to write the file.
SIXOTH	Specifies permission for users in the file other class to search, if the file is a directory, or to execute, for any other file.
SIRWXO	Specifies permission for users in the file other class to read, write, and search, if the file is a directory, or to read, write, and execute, for any other file. this value is the bit inclusive or of SIROTH, SIWOTH, and SIXOTH.
SISUID	Specifies that the system set the user id of the process to be the same as the user id of the file owner when the file is run as a program.
SISGID	Specifies that the system set the file group of the process to be the same as the group id of the file owner when the file is run as a program.

Top

File Option descriptions for PATHOPTS parameter

Sub-Parameter	Definition
ORDONLY	Specifies that the program can open the file for reading.
OWRONLY	Specifies that the program can open the file for writing.
ORDWR	Specifies that the program can open the file for reading and writing. Do not use this option for a FIFO special file; the result is undefined.
OAPPEND	Specifies that the system sets the file offset to the end of the file before each write, so that data is written at the end of the existing file.
OCREAT	Specifies that the system is to create the file. If the file already exists, the operation will fail if OEXCL is specified, and will open the existing file if OEXCL is not specified.
OEXCL	Specifies that, if the file already exists, then HFS open file processing will fail. Note: The system ignores OEXCL if OCREAT is not also specified.
ONOCTTY	Specifies that, if the patterning of the file will not make the terminal device the controlling a terminal device, then op
ONONBLOCK	Specifies the following, depending on the type of file: For FIFO special files: With ONONBLOCK specified and ORDONLY access: an open() function for reading-only returns without delay. With ONONBLOCK not specified and ORDONLY access: an open() function for reading-only blocks (waits) until a process opens the file for writing. With ONONBLOCK specified and OWRONLY access: an open() function for writing-only returns an error if no process currently has the file open for reading. With ONONBLOCK not specified and OWRONLY access: an open() function for writing-only blocks (waits) until a process opens the file for reading. For character special files: If ONONBLOCK is specified: an open() function returns without blocking (waiting) until the device is ready or available. Device response depends on the type of device. If ONONBLOCK is not specified: an open() function blocks (waits) until the device is ready or available. Specification of ONONBLOCK has no other effects.
OSYNC	Specifies that the system is to move data from buffer storage to disk (or other permanent storage) before returning control from a callable service that performs a write.
OTRUNC	Specifies that the system is to truncate the file length to zero if all of the following are true: The file specified on the path operand exists The file is a regular file The file successfully opened with ORDWR or OWRONLY The system does not change the mode and owner. OTRUNC has no effect on FIFO special files or terminal device files.

Top

PL/I Example


 
    %INCLUDE SPCPHD
       .
       .
       .
       .
    DCL  COMMAND         CHAR(80)              /* ALLOCATE COMMAND */
         INIT('DSN(SWS.INPUT.DATA) DDN(INFILE) DISP(SHR)');
    DCL  CMDLEN          FIXED BIN(31);        /* COMMAND LENGTH   */
    DCL  RC              FIXED BIN(31);        /* RETURN CODE      */
 
    CMDLEN = LENGTH(COMMAND);                  /* SET COMMAND LEN  */
 
 
    /* DYNAMICALLY ALLOCATE AN INPUT FILE                          */
 
    CALL SWSALLOC(CMDLEN,               /* COMMAND LENGTH          */
                  COMMAND,              /* COMMAND                 */
                  SWSASB);              /* ALLOCATION STATUS BLOCK */
 
    RC = PLIRETV();                     /* GET RETURN CODE         */
    IF RC ^= SWS_SUCCESS THEN           /* EXIT PROGRAM IF BAD RC  */
       EXIT;

Top

C Example


 
    SWS_ALLOCATION_STATUS_BLOCK swsASB; /* response area           */
       .
       .
       .
       .
    long RC;                            /* return code             */
    char szCommand[] = "DSN(SWS.INPUT.DATA) DDN(INFILE) DISP(SHR)";
 
 
    /* Dynamically allocate an input file                          */
 
    rc = SWSAlloc(strlen(szCommand),    /* Command Length          */
                  szCommand,            /* Command                 */
                  swsASB);              /* Response area           */
 
    if (rc ^= SWS_SUCCESS)
       do
         printf(swsASB.Error_Message);
         return rc;
       end

Top

COBOL Example


 
  *     NEON API COPY BOOK
    COPY SBCPHD.
        .
        .
        .
        .
    77   COMMAND-LENGTH       PIC S9(5) COMP.
    77   COMMAND              PIC X(80)
         VALUE 'DSN(SWS.INPUT.DATA) DDN(INFILE) DISP(SHR)'.
 
  *     DYNAMICALLY ALLOCATE AN INPUT FILE
 
    MOVE 80 TO COMMAND-LENGTH.
    CALL SWSALLOC
        USING COMMAND-LENGTH,
              COMMAND,
              SWS-ALLOCATION-STATUS-BLOCK.
 
    MOVE RETURN-CODE TO WS-SWSAPI-RETURN-CODE.
    IF NOT SWS-SUCCESS
        DISPLAY 'INFILE ALLOCATION FAILED.' UPON CONSOLE
        DISPLAY SWSASB-ERROR-MESSAGE UPON CONSOLE
        GOBACK.

Top