Script APIs

Script API Introduction

APIs are provided which allow developers to build scripts. API interfaces are provided for four different programming environments:

OPM and Rexx/400 interfaces are provided by programs in library WWWSERVER.

The WWWAPI service program in library WWWSERVER provides the ILE entry points. A bind directory named BNDDIR in library WWWSERVER is provided to aid in developing ILE applications.

Includes are provided to aid in developing scripts in the following programming environments:

ILE C
Macros are provided for ILE C applications to help in migrating C scripts from other environments to the AS/400. See the member WWWAPI in source file H (i.e., WWWAPI.H) in library WWWSERVER for more information on ILE C interfaces.
ILE RPG
Constants that define ILE API entry points for ILE RPG applications are available in member DWWWAPI in WWWSERVER/QRPGLESRC.
ILE COBOL
Data items that define ILE API entry points for ILE COBOL applications are available in member WWWAPI in WWWSERVER/QCBLLESRC.
COBOL
Data items that define API entry points for COBOL applications are available in member WWWAPI in WWWSERVER/QCBLSRC.

Script APIs

The following documents each of the script APIs that are available. Under each API there are three interface descriptions:
  1. The first describes the ILE C interface.
  2. The second describes the general ILE and OPM interface. The ILE entry point is listed first followed by the OPM program name in parenthesis.
  3. The third describes the Rexx/400 interface. All Web Server/400 APIs are accessed through the WWWRexx Rexx/400 function. The first parameter is a string that indicates which API to perform.
Each API requires all of the parameters that are listed. For APIs that return binary values that indicate success or failure, a negative number always indicates an error occurred. Note that in the documentation Bytes Provided is sometimes abbreviated to BP and Bytes Available to BA to improve readability.

The following is a directory of the available APIs:

Get Form Variable
Get Form Variable Enum
Read
Write, Write with Carriage Return and Line Feed, Write Header
Get Environment Variable
UnEscape Read Data
Escape Data
Printf

Get Form Variable

Get form variable is used to retrieve a form variable that was passed to the script from the browser. Get form variable is independent of the method used to send the form data to the script. The value returned is unescaped.

The Get Form Variable Enum function can be used to retrieve form variables that have or can have multiple values.

WwwGetFormVarc

Prototype: 
char *WwwGetFormVarc(char *pszFormVar);

where,

pszFormVar is the null-terminated name of the form variable to retrieve. The name is dependent on the form being processed.

Return Value: Pointer to the null-terminated form variable's value. Do not attempt to free the returned pointer.

Return values: 

NULL  : pszFormVar is NULL
other : Form variable value; empty string is returned if
        value not found or set
WwwGetFormVar (WWWGETFV)

Parameters: 
  1. Form Variable                   Input  Char(*)

  2. Form Variable Length            Input  Binary(4)

  3. Variable Value                  Output Char(*)

  4. Variable Value Bytes Provided   Input  Binary(4)

  5. Variable Value Bytes Available  Output Binary(4)
where,

Form Variable is the name of the form variable to retrieve. The name is dependent on the form being processed.

Form Variable Length is the length of the form variable name.

Variable Value is the returned form variable value.

Variable Value Bytes Provided is the number of bytes provided for the form variable value.

Variable Value Bytes Available is the length of the form variable value.

Bytes available return values: 

0 > BA <= BP : Complete form variable value returned
     BA > BP : Partial form variable value returned
           0 : Form variable value not found or set
          -1 : Form variable length parameter is less than
               or equal to zero or greater than 1024
          -2 : Variable value BP is less than or equal to zero
         -98 : Required parameter was omitted
         -99 : Internal error occurred (e.g., memory could not
               be allocated)
Rexx/400

Prototype: 
Value = WWWRexx("GETFORMVAR", FormVariableName)

where,

WWWRexx is the Rexx/400 function that handles all Web Server/400 API calls.

"GETFORMVAR" is the verb that performs the Get Form Variable API. This is a static string.

FormVariableName is the name of the HTML form variable to retrieve. The name is dependent on the form being processed.

Return Value: A string containing the value of the HTML form variable.

Get Form Variable Enum

Get form variable enum is used to retrieve a form variable value that was passed to the script from the browser. Get form variable enum is needed to retrieve a form variable's value when the form variable has multiple values (e.g., multiple selection lists). A program must loop, changing the value retrieving, to retrieve all of the form variable's values.

Get form variable enum is independent of the method used to send the form data to the script. The value returned is unescaped.

WwwGetFormVarEnumc

Prototype: 
char *WwwGetFormVarEnumc(char *pszFormVar,
                         long lNumber);

where,

pszFormVar is the null-terminated name of the form variable to retrieve. The name is dependent on the form being processed.

lNumber identifies the form variable value to retrieve. The first value has a number of 1, the second value has a number of 2, and so on for the rest of the values. All of the values have been retrieved when the next number does not return a value.

Return Value: Pointer to the null-terminated form variable's value. Do not attempt to free the returned pointer.

Return values: 

NULL  : pszFormVar is NULL
other : Form variable value; empty string is returned if
        value not found or set
WwwGetFormVarEnum (WWWGETFE)

Parameters: 
  1. Form Variable                   Input  Char(*)

  2. Form Variable Length            Input  Binary(4)

  3. Number                          Input  Binary(4)

  4. Variable Value                  Output Char(*)

  5. Variable Value Bytes Provided   Input  Binary(4)

  6. Variable Value Bytes Available  Output Binary(4)
where,

Form Variable is the name of the form variable to retrieve. The name is dependent on the form being processed.

Form Variable Length is the length of the form variable name.

Number identifies the form variable value to retrieve. The first value has a number of 1, the second value has a number of 2, and so on for the rest of the values. All of the values have been retrieved when the next number does not return a value.

Variable Value is the returned form variable value.

Variable Value Bytes Provided is the number of bytes provided for the form variable value.

Variable Value Bytes Available is the length of the form variable value.

Bytes available return values: 

0 > BA <= BP : Complete form variable value returned
     BA > BP : Partial form variable value returned
           0 : Form variable value not found or set
          -1 : Form variable length parameter is less than
               or equal to zero or greater than 1024
          -2 : Variable value BP is less than or equal to zero
          -4 : Number is less than or equal to zero
         -98 : Required parameter was omitted
         -99 : Internal error occurred (e.g., memory could not
               be allocated)
Rexx/400

Prototype: 
Value = WWWRexx("GETFORMVAR", FormVariableName, Number)

where,

WWWRexx is the Rexx/400 function that handles all Web Server/400 API calls.

"GETFORMVAR" is the verb that performs the Get Form Variable API. This is a static string.

FormVariableName is the name of the HTML form variable to retrieve. The name is dependent on the form being processed.

Number identifies the form variable value to retrieve. The first value has a number of 1, the second value has a number of 2, and so on for the rest of the values. All of the values have been retrieved when the next number does not return a value.

Return Value: A string containing the value of the HTML form variable.

Read

Read is used to read script data from standard input. The data is sent by a browser using a POST or PUT method.

WwwReadc

Prototype: 
long WwwReadc(void *pBuffer,
              long lBufferSize);

where,

pBuffer is the return buffer.

lBufferSize is the size in bytes of the return buffer.

Return Value: Number of bytes returned in the buffer.

Return values: 

 >0 : Number of bytes read into the buffer
  0 : No data to read
 -1 : Buffer size is less than or equal to zero
-98 : Required parameter was omitted
WwwRead (WWWREAD)

Parameters: 
  1. Return Buffer                   Output Char(*)

  2. Return Buffer Size              Input  Binary(4)

  3. Bytes Read                      Output Binary(4)
where,

Return Buffer is the buffer in which to return the data read.

Return Buffer Size is the size in bytes of the return buffer.

Bytes Read is the number of bytes returned in the buffer.

Bytes read return values: 

 >0 : Number of bytes read into the buffer
  0 : No data to read
 -1 : Return buffer size is less than or equal to zero
-98 : Required parameter was omitted
Rexx/400

Prototype: 
Buffer = WWWRexx("READ", MaxBytesToRead)

where,

WWWRexx is the Rexx/400 function that handles all Web Server/400 API calls.

"READ" is the verb that performs the Read API. This is a static string.

MaxBytesToRead is maximum number of bytes to read.

Return Value: A string containing what was read.

Write

Write is used to send script data back to the browser. The write functions suffixed with CrLf add a carriage return (i.e., CR) and line feed (i.e., LF) after the data being sent. This is used to format the data so it is not all on one line. The write functions suffixed with Header add 2 CR,LF pairs after the data being sent. These functions can be used to send the document header, which requires a blank line between the header and the data that follows. Note that data being returned from the script is not sent to the browser until the script ends.

WwwWritec
WwwWriteCrLfc
WwwWriteHeaderc

Prototype: 
long WwwWritec(void *pBuffer,
               long  lBytesToWrite);

long WwwWriteCrLfc(void *pBuffer,
                   long  lBytesToWrite);

long WwwWriteHeaderc(void *pBuffer,
                     long  lBytesToWrite);

where,

pBuffer is the buffer containing the data to write.

lBytesToWrite is the number of bytes to write.

Return Value: Number of bytes written.

Return values: 

 >0 : Number of bytes written
  0 : No data written
 -1 : Bytes to write is less than zero
-98 : Required parameter was omitted
WwwWrite (WWWWRITE)
WwwWriteCrLf (WWWWRTCL)
WwwWriteHeader (WWWWRTHD)

Parameters: 
  1. Input Buffer                    Input  Char(*)

  2. Bytes To Write                  Input  Binary(4)

  3. Bytes Written                   Output Binary(4)
where,

Input Buffer contains the data to write.

Bytes To Write is the number of bytes to write.

Bytes Written is the number of bytes written.

Bytes written return values: 

 >0 : Number of bytes written
  0 : No data written
 -1 : Bytes to write is less than zero
-98 : Required parameter was omitted
Rexx/400

Note that a normal Rexx/400 SAY will send its output over standard output and can be used in place of the WRITE API in Rexx/400. Important: The OS/400 PTF SF26297 must be applied to V3R1 systems for the SAY to work. If this PTF is not applied and a SAY with no parameters is included in your Rexx/400 procedure, the procedure will cause an exception.

Function Prototype: 
BytesWritten = WWWRexx("WRITE", DataExpression)
BytesWritten = WWWRexx("WRITECRLF", DataExpression)
BytesWritten = WWWRexx("WRITEHEADER", DataExpression)

Procedure Prototype: 
CALL WWWRexx "WRITE", DataExpression
CALL WWWRexx "WRITECRLF", DataExpression
CALL WWWRexx "WRITEHEADER", DataExpression

where,

WWWRexx is the Rexx/400 function that handles all Web Server/400 API calls.

"WRITE", "WRITECRLF", and "WRITEHEADER" are the verbs that perform the Write API. These are static strings.

DataExpression is the expression to write.

Return Value: The number of bytes written.

Get Environment Variable

Get environment variable is used to retrieve a script environment variable value.

WwwGetEnvc

Prototype: 
char *WwwGetEnvc(char *pszEnvVar);

where,

pszEnvVar is the null-terminated name of the environment variable to retrieve.

Return Value: Pointer to the null-terminated environment variable's value. Do not attempt to free the returned pointer.

Return values: 

NULL  : pszEnvVar is NULL
other : Environment variable value; empty string is returned
        if value not found or set
WwwGetEnv (WWWGETEN)

Parameters: 
  1. Environment Variable            Input  Char(*)

  2. Environment Variable Length     Input  Binary(4)

  3. Variable Value                  Output Char(*)

  4. Variable Value Bytes Provided   Input  Binary(4)

  5. Variable Value Bytes Available  Output Binary(4)
where,

Environment Variable is the name of the environment variable to retrieve.

Environment Variable Length is the length of the environment variable name.

Variable Value is the returned environment variable value.

Variable Value Bytes Provided is the number of bytes provided for the environment variable value.

Variable Value Bytes Available is the length of the environment variable value.

Bytes available return values: 

0 > BA <= BP : Complete environment variable value returned
     BA > BP : Partial environment variable value returned
           0 : Environment variable value not found or set
          -1 : Environment variable length parameter is less
               than or equal to zero or greater than 1024
          -2 : Variable value BP is less than or equal to zero
         -98 : Required parameter was omitted
         -99 : Internal error occurred (e.g., memory could not
               be allocated)
Rexx/400

Prototype: 
Value = WWWRexx("GETENV", EnvironmentVariableName)

where,

WWWRexx is the Rexx/400 function that handles all Web Server/400 API calls.

"GETENV" is the verb that performs the Get Environment Variable API. This is a static string.

EnvironmentVariableName is the name of the environment variable to retrieve.

Return Value: A string containing the value of the environment variable.

UnEscape Read Data

Unescape read data is used to unescape data received from browser. This will convert the URL escape sequences to EBCDIC characters (e.g., %41 goes to an EBCDIC "A" and a "+" goes to a space).

WwwUnEscapec

Prototype: 
long WwwUnEscapec(char *pszEscaped,
                  char *pszUnEscaped);

where,

pszEscaped is the null-terminated buffer containing the data to unescape.

pszUnEscaped is the null-terminated buffer in which to return the unescaped data. If the pointer is NULL the unescaped data is returned in the escaped buffer (i.e., unescaped in place).

Return Value: Number of unescaped bytes in the return buffer.

Return values: 

>=0 : Number of unescaped bytes
-98 : Required parameter was omitted
WwwUnEscape (WWWUNESC)

Parameters: 
  1. Unescape In Place               Input  Char(1)

  2. Escaped Buffer                  I/O    Char(*)

  3. Escaped Length                  Input  Binary(4)

  4. Unescaped Buffer                Output Char(*)

  5. Unescaped Bytes Provided        Input  Binary(4)

  6. Unescaped Bytes Available       Output Binary(4)
where,

Unescape In Place indicates which buffer to return the unescaped data in. A value of '1' returns the data in the escaped buffer. A value of '0' returns the data in the unescaped buffer.

Escaped Buffer contains the data to unescape.

Escaped Length is the number of bytes to unescape.

Unescaped Buffer is the buffer in which to return the unescaped data. Not used if unescape in place is set to '1'.

Unescaped Bytes Provided is the number of bytes provided for the unescaped data. Must be greater than or equal to the escaped length. Not used if unescape in place is set to '1'.

Unescaped Bytes Available is the number of unescaped bytes in the return buffer.

Bytes available return values: 

>=0 : Number of unescaped bytes
 -1 : Escaped length parameter is less than or equal to zero
 -2 : Unescaped BP is less than escaped length
 -3 : Unescape in place parameter is invalid
-98 : Required parameter was omitted
-99 : Internal error occurred (e.g., memory could not be
      allocated)
Rexx/400

Prototype: 
Unescaped = WWWRexx("UNESCAPE", EscapedData)

where,

WWWRexx is the Rexx/400 function that handles all Web Server/400 API calls.

"UNESCAPE" is the verb that performs the Unescape Read Data API. This is a static string.

EscapedData is the value to unescape.

Return Value: A string containing the unescaped data.

Escape Data

Escape is used to escape data before sending to the browser. Characters not in the safe URL character set are URL escaped. EBCDIC characters are escaped to the hexadecimal representation of their ASCII code point and spaces are changed to pluses ("+").

WwwEscapec

Prototype: 
long WwwEscapec(char *pszUnEscaped,
                char *pszEscaped,
                long lEscapedBytesProvided);

where,

pszUnEscaped is the null-terminated buffer containing the data to escape.

pszEscaped is the null-terminated buffer in which to return the escaped data. If the pointer is NULL the escaped data is returned in the unescaped buffer (i.e., escaped in place).

lEscapedBytesProvided is the number of bytes provided for the escaped data.

Return Value: Number of escaped bytes available.

Return values: 

0 >= BA <= BP : All escaped data returned
      BA > BP : Partial escaped data returned
           -2 : Escaped BP is less than or equal to the
                unescaped length
          -98 : Required parameter was omitted
WwwEscape (WWWESC)

Parameters: 
  1. Escape In Place                 Input  Char(1)

  2. Unescaped Buffer                I/O    Char(*)

  3. Unescaped Length                Input  Binary(4)

  4. Escaped Buffer                  Output Char(*)

  5. Escaped Bytes Provided          Input  Binary(4)

  6. Escaped Bytes Available         Output Binary(4)
where,

Escape In Place indicates which buffer to return the escaped data in. A value of '1' returns the data in the unescaped buffer. A value of '0' returns the data in the escaped buffer.

Unescaped Buffer contains the data to escape.

Unescaped Length is the number of bytes to escape.

Escaped Buffer is the buffer in which to return the escaped data. Not used if escape in place is set to '1'.

Escaped Bytes Provided is the number of bytes provided for the escaped data. Must be greater than or equal to the unescaped length. Not used if escape in place is set to '1'.

Escaped Bytes Available is the number of escaped bytes available.

Bytes available return values: 

0 >= BA <= BP : All escaped data returned
      BA > BP : Partial escaped data returned
           -1 : Unescaped length parameter is less than or
                equal to zero
           -2 : Escaped BP is less than unescaped length
           -3 : Escape in place parameter is invalid
          -98 : Required parameter was omitted
          -99 : Internal error occurred (e.g., memory could
                not be allocated)
Rexx/400

Prototype: 
EscapedData = WWWRexx("ESCAPE", UnescapedData)

where,

WWWRexx is the Rexx/400 function that handles all Web Server/400 API calls.

"ESCAPE" is the verb that performs the Escape Data API. This is a static string.

UnescapedData is the value to escape.

Return Value: A string containing the escaped data.

Printf

Printf is used to return formatted script data to the browser. Printf is only available to ILE C applications. The parameters are the same as the C printf function. Note that data being returned from the script is not sent to the browser until the script ends.

WwwPrintfc

Prototype: 
long WwwPrintfc(char *pszFormat,...);

where,

pszFormat is the null-terminated formatting string. This string, when expanded, cannot exceed 8K in length.

... are the variables required by the format string.

Return Value: Number of bytes sent to the browser.

Return values: 

>=0 : Number of bytes sent to the browser
-98 : Required parameter was omitted