High-Level Language SWSFREE (SWCPFR) Function
Related Topics
 |
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.
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:
|
| 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:
|
| SPIN(VALUE) | Specifies when a sysout data set is printed. Legitimate values are:
|
| 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:
|
| 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:
|
| 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:
|
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;
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
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.