Previous Topic
Table Of Contents
Parent Topic
Next Topic

High-Level Language SWSECURE (SWCPSC) Function

Related Topics

Web Server API Function Index

SWSECURE is a built in function used to do security authorization processing. The function is divided into six different subfunctions each of which provide a different type of security authorization processing. 

Call Arguments

The SWSECURE function takes a varying number of arguments depending on the subfunction requested. The subfunction request itself is designated via the second entry in the parameter list passed to the SWSECURE function. 

Return Values

SWSECURE returns both a numeric code and a character response if the subfunction call was a success. If the subfunction call failed due to a validation error, only a numeric code is returned. However, if the call was processed by the MVS security subsystem, the actual text results are returned to the "output buffer" location specified on each call which is designated by the third entry in the parameter. Allocate an area of at least 256 bytes for the return of the result text. 

SWS_SUCCESS

The requested operation succeeded. The return value has been determined and placed into the buffer area. The actual size of the data is set into the fourth argument.

SWS_SUCCESS_WITH_INFO

The return buffer was not large enough to store the return value. The return value was truncated. The size of the return value, before truncation, is set in the fourth argument. For character data, a null termination byte is always placed into the last position of the output buffer area.

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.

SWS_INVALID_HANDLE

The connection handle argument is invalid.

 

SWSECURE Dataset Access parameter list

Return Values

The function returns the string "ALLOW" if the specified type of access to the data set is allowed. Otherwise, an error message is returned. The error message is generated either by the MVS Security Subsystem (RACF, CA-ACF2, etc.) or by the Server.  For example: 

      RESOURCE NOT PROTECTED BY RACF
      RESOURCE ACCESS DENIED BY RACF

Top

SWSECURE Fetching Logon ID Field Data parameter list

Return Values

Shadow/REXX does the following conversions depending on field format: 

• Binary fields are converted to signed decimal values without leading zeros or blanks. The number zero is returned as 0. 
• Character fields are returned as is, possibly truncated to the Shadow/REXX defined maximum valid string length. 
• Date fields are converted to the form yyyy/mm/dd with leading zeros kept (so that the result is always exactly ten non-blank characters). A zero date field is returned as the string ****/**/**. 
• Bit fields are converted to a 0 (FALSE or off) or a 1 (TRUE or on). 
• The group list field inquiry is handled separately. The function returns a integer count of the number of group entries found in the list. Each individual group name is returned as a separate entry in the external data queue. 

Top

SWSECURE Requesting Security Product Information parameter list

Return Values

The function returns a string with the requested information. If the information cannot be obtained, a NULL string is returned. 

Top

SWSECURE Generalized Resource Rule Checks parameter list

Returned Values

For any of the three security products, if the specified access to the resource is allowed, the Server returns the string ALLOW.  Otherwise, an error message is returned. The error message is generated either by the MVS Security Subsystem (RACF, CA-ACF2, etc.) or by the Server.  For example: 

  RESOURCE NOT PROTECTED BY RACF
  RESOURCE ACCESS DENIED BY RACF

Top

SWSECURE Password Validation parameter list

Return Values

For all three security products, if the password was correct (and a new password was assigned if specified), the returned value is the string ALLOW.  Otherwise, an error message is returned. The error message is generated either by the MVS Security Subsystem (RACF, CA-ACF2, etc.) or by the Server.  For example: 

     INVALID SECURITY ENVIRONMENT
     USER PROFILE NOT DEFINED TO RACF
     PASSWORD IS NOT AUTHORIZED
     PASSWORD HAS EXPIRED
     USER NOT DEFINED TO THE GROUP
     REJECTED BY INSTALLATION EXIT
     ACCESS HAS BEEN REVOKED
     RACF IS NOT ACTIVE
     GROUP ACCESS HAS BEEN REVOKED
     NOT AUTHORIZED TO USE THIS TERMINAL
     INVALID DAY OR TIME OF DAY
     TERMINAL CANNOT BE USED
     NOT AUTHORIZED TO USE APPLICATION

Note: For CA-ACF2, invalid password attempt calls increase the invalid password violation counter for the specified user ID. 

Top

EXAMPLES

The following examples demonstrate the password validation subfunction of the SWSECURE HLL API. 

PL/I Example

DCL SCONN PTR;             /* Connection Handle     */ 
DCL SBUFF CHAR(256);       /* Output Buffer         */ 
DCL SBFSZ FIXED BIN(31);   /* Output Buffer length  */ 
DCL SUID CHAR(8);          /* Userid                */  
DCL SUIDSZ FIXED BIN(31);  /* Userid Length         */ 
DCL PSWD CHAR(8);          /* Password              */ 
DCL PSWDSZ FIXED BIN(31);  /* Password Length       */  

ADDR(SCONN)->DMHX=0;        /* Zero connection handle*/ 
SUID="USERID";              /* Set Userid            */ 
SUIDSZ=6;                   /* Set Userid length     */ 
PSWD="PASSWORD";            /* Set Password          */ 
PSWDSZ=8;                   /* Set Password length   */ 
CALL SWSECURE(SCONN         /* Call the function     */ 
     SWS_SECURE_VALPSWD, 
     SBUFF, 
     SFFSZ, 
     SUID, 
     SUIDSZ, 
     SPSWD, 
     SPWDSZ); 

RC=PLIRETV();               /* Get return code       */ 
IF RC ^=SWS_SUCCESS THEN    /* exit if bad RC        */ 
EXIT;

C Example

COBOL Example

77 SCONN USAGE IS POINTER. 
77 HBUFF PIC X(80). 
77 HBUFFSZ PIC S9(5) COMP. 
77 HUID PIC X(8) 
77 HUIDSZ PIC S9(5) COMP. 
77 HPSWD PIC X(8). 
77 HPSWDSZ PIC S9(5) COMP. 
MOVE 80 TO HBUFFSZ 
MOVE "USERID" TO HUID. 
MOVE 6 TO HUIDSZ. 
MOVE "PASSWORD" TO HPSWD. 
MOVE 8 TO HPSWDSZ. 
CALL "SWCPSC" USING SCONN, 
SWS-SECURE-VFYDSN, 
HBUFF, 
HBUFFSZ, 
BDATA, 
BSIZE. 
MOVE RETURN CODE TO WS-SWSAPI-RETURN-CODE. 
IF NOT SWS-SUCCESS GOBACK/

Top