Previous Topic Table Of Contents Parent Topic Next Topic |  | # High-Level Language SWSFREE (SWCPFR) 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 SWCPFR
SWSFREE is the Web Server API function used to de-allocate datasets. The SWSFREE API dynamically de-allocates a data set and/or an HFS file. You may also change the output class of a sysout dataset, making it immediately available for processing by an output writer, while de-allocating them. The original dataset disposition, set when the dataset was dynamically allocated, may be overridden during de-allocation. The format of this command is similar in features and functions to the TSO/E Free command. A text string is used as input in order to provide the parameters necessary to de-allocate the specified dataset. ## SWCPFR Call Arguments The SWSFREE (SWCPFR) function arguments are described in the table which follows.
Arg. No. | HLL Argument Type | I/O | Description of Argument
--- | --- | --- | ---
C | COBOL | PL/I
1 | LONG | PIC S9(5) COMP | FIXED BIN(31) | Input | The length of the de-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 de-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 de-allocation command string. See Supported dynamic de-allocation keywords below.
3 | SWSASB * | Usage pointer | PTR | Output | The Shadow OS/390 Web Server Allocation Status Block. This is an required argument that provides information concerning the status of the de-allocation request.

## Return Values

SWSFREE 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 de-allocation keywords

The SWSFREE (SWCPFR) interface supports the following dataset de-allocation request parameters:

DSN(DSNAME) | Specifies the name of the dataset to be de-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.
PATH(PATHNAME) | Identifies an HFS file to be de-allocated. 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.
DDN(DDNAME) | Specifies the DDNAME, of the datasets, to be de-allocated. This is a required field.
MEMBER(VALUE) | Specifies the member name of a dataset to allocate or it may also be the relative Generation Data Group number of the dataset. Examples:
         DSN(SYS1.PROCLIB) MEMBER(JES2)
         DSN(ANY.BASE.DSN) MEMBER(+1)
Note: Generation dataset relative numbers are not catalogued until the dataset is de-allocated or the Shadow OS/390 Web Server address space is terminated.
DEST(DESTINATION/NODE USERID) | Remote destination or a User at a specified node to which SYSOUT data sets are to be routed.
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.
SYSOUT(CLASS) | Dataset is to be a system output dataset
DISP(NORMAL) | Specifies the disposition of file upon de-allocation. Legitimate values are: 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.
HOLD | Dataset is to be placed on a hold queue upon de-allocation
NOHOLD | Dataset is not to be placed on a hold queue upon unallocation
PATHDISP(NORMAL) | Specifies the disposition of an HFS file upon normal session termination. Use one of the following dispositions: KEEP = Specifies that the file should be kept. DELETE = Specifies that the file should be deleted.
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

## PL/I Example

        %INCLUDE SPCPHD
           .
           .
           .
           .
        DCL  COMMAND         CHAR(80)              /* ALLOCATE COMMAND */
             INIT('DDN(INFILE)');
        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 SWSFREE(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[] = "DDN(INFILE)";

          /* Dynamically de-allocate a dataset by it's DDName            */

          rc = SWSFree(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
                 'DDN(INFILE)'.

          *     DYNAMICALLY DE-ALLOCATE A DATASET BY IT'S DDNAME

            MOVE 80 TO COMMAND-LENGTH.
            CALL SWSFREE
                USING COMMAND-LENGTH,
                      COMMAND,
                      SWS-ALLOCATION-STATUS-BLOCK.

            MOVE RETURN-CODE TO WS-SWSAPI-RETURN-CODE.
            IF NOT SWS-SUCCESS
                DISPLAY 'INFILE DE-ALLOCATION FAILED.' UPON CONSOLE
                DISPLAY SWSASB-ERROR-MESSAGE UPON CONSOLE
                GOBACK.

Top