WebAPI Function Reference

Table of Contents

Introduction Function Naming and Calling Convention
Function Return Values
Navigation Within the WebObject Variable Directories ServerGetConfig
ServerGetServer
ServerGetConnect
ServerGetRequest
ServerGetParameters
ServerGetArguments
ServerFind
Querying a WebObject Variable's Attributes ServerKind
ServerSize
ServerName
Reading the Contents of a WebObject Variable ServerReadInteger
ServerReadFloat
ServerReadText
ServerReadBinary
Overwriting the Contents of a WebObject Variable ServerFlush
ServerWriteInteger
ServerWriteFloat
ServerWriteText
ServerWriteBinary
Appending to the Existing Contents of a WebObject Variable ServerAppendText
ServerAppendBinary
ServerPrint
Creating New WebObject Variables ServerNewInteger
ServerNewFloat
ServerNewText
ServerNewBinary
ServerNewSemaphore
ServerDelete
Browsing Through the WebObject Variable Directory Hierarchy ServerParent
ServerChild
ServerSibling
Utility Functions ServerInterpret
ServerGetError
ServerGetParcel
ServerGetFunction

The API functions have been carefully designed to minimise incompatibilities across languages and operating systems, protecting your investment and leveraging your existing skill set.

Function Naming and Calling Convention

The API Function names are identical in both C and Rexx. With Perl, simply replace the prefix "Server" with "WebPerl::" instead.

The function input parameters are provided in the same sequence in all languages. Some languages have different ways and capabilities of returning information, so each language has a separate section that specifies the exact function prototype for each API function.

With Rexx and Perl, the automatic dynamic memory management is taken full advantage of when returning text or binary data. There is no limit (other than available virtual memory) on the amount of data that can be transferred between PowerWeb and an API extension written in any language.

Function Return Values

When an API extension needs to call PowerWeb, it uses one of a family of library functions. All these functions have common standardised return values:

Symbolic Name	Value
ERR_INTERNAL	-3
ERR_MEMORY	-2
ERR_BAD_ARGUMENTS	-1
ERR_NONE	0
ERR_NOT_FOUND	1
ERR_NO_LONGER_EXISTS	2
ERR_ACCESS_DENIED	3
ERR_BUSY	4
ERR_INVALID_TYPE	5
ERR_NOT_A_LIST	6
ERR_VALUE_TRUNCATED	7
ERR_INCOMPATIBLE_VERSION	8
ERR_BAD_NAME	9

Under Perl, if there is an error, the function will return undef, and the specific error code can be obtained through the function WebPerl::GetError().

Get a handle to the "Config:/" variable sub-directory.

C Example:
rc = ServerGetConfig(parcel, &handleConfig);

Rexx Example:
handleConfig = ServerGetConfig(parcel)

Perl Example:
$handleConfig = WebPerl::GetConfig($parcel);

Get a handle to the "Server:/" variable sub-directory.

C Example:
rc = ServerGetServer(parcel, &handleServer);

Rexx Example:
handleServer = ServerGetServer(parcel)

Perl Example:
$handleServer = WebPerl::GetServer($parcel);

Get a handle to the "Connect:/" variable sub-directory.

C Example:
rc = ServerGetConnect(parcel, &handleConnect);

Rexx Example:
handleConnect = ServerGetConnect(parcel)

Perl Example:
$handleConnect = WebPerl::GetConnect($parcel);

Get a handle to the "Request:/" variable sub-directory.

C Example:
rc = ServerGetRequest(parcel, &handleRequest);

Rexx Example:
handleRequest = ServerGetRequest(parcel)

Perl Example:
$handleRequest = WebPerl::GetRequest($parcel);

Get a handle to the "Parameter:/" variable sub-directory.

C Example:
rc = ServerGetParameters(parcel, &handleParam);

Rexx Example:
handleParameters = ServerGetParameters(parcel)

Perl Example:
$handleParameters = WebPerl::GetParameters($parcel);

Get a handle to the "Argument:/" variable sub-directory.

C Example:
rc = ServerGetArguments(parcel, &handleArgument);

Rexx Example:
handleArguments = ServerGetArguments(parcel)

Perl Example:
$handleArguments = WebPerl::GetArguments($parcel);

Get a handle to the variable with a specified name. The name can be absolute or relative to the handle passed over as a first parameter.

C Example 1:
rc = ServerGetRequest(parcel, &handleRequest);
rc = ServerFind(handleRequest, "Resource", &handleVariable);

C Example 2:
rc = ServerGetConfig(parcel, &handleConfig);
rc = ServerFind(handleConfig, "/Servers/HTTP", &handleHTTP);
rc = ServerFind(handleHTTP, "ErrorFile", &handleFile);

Rexx Example 1:
handleRequest = ServerGetRequest(parcel)
handleVariable = ServerFind(handleRequest, "Resource")

Rexx Example 2:
handleConfig = ServerGetConfig(parcel)
handleHTTP = ServerFind(handleConfig, "/Servers/HTTP")
handleFile = ServerFind(handleHTTP, "ErrorFile")

Perl Example 1:
$handleRequest = WebPerl::GetRequest($parcel);
$handleVariable = WebPerl::Find($handleRequest, 'Resource');

Perl Example 2:
$handleConfig = WebPerl::GetConfig($parcel);
$handleHTTP = WebPerl::Find($handleConfig, '/Servers/HTTP');
$handleFile = WebPerl::Find($handleHTTP, 'ErrorFile');

Returns the data type of the indicated variable:

1. 32-bit signed integer
2. Double-precision floating point
3. Variable-length text
4. Variable-length binary buffer
5. List that contains other Variables
6. Pointer to another WebObject Variable

C Example:
rc = ServerFind(parcel, "Config:/Servers", &handleServers);
rc = ServerKind(handleServers, &iKind);


Returns the size in bytes of the indicated variable, unless it is a List variable, in which case it returns the number of variables contained in that list.

C Example:
rc = ServerFind(parcel, "Config:/Servers", &handleServers);
rc = ServerSize(handleServers, &cServers);


Returns the name of the indicated variable. Often used in conjunction with the hierarchy browsing functions described below.

C Example:
rc = ServerGetConfig(parcel, &handleConfig);
rc = ServerChild(handleConfig, &handleFirst);
rc = ServerName(handleFirst, buffer, sizeof(buffer));


Perl Example:
$handleConfig = WebPerl::GetConfig($parcel);
$handleFirst = WebPerl::Child($handleConfig);
$name = WebPerl::Name($handleFirst);


Reads the indicated variable and converts it (if necessary) into a 32 bit signed integer.

C Example:
rc = ServerReadInteger(parcel, "Server:/Stats/Clients", &iClients);

Perl Example:
$clients = WebPerl::ReadInteger($parcel, 'Server:/Stats/Clients');

Reads the indicated variable and converts it (if necessary) into a double precision floating point number.

C Example:
rc = ServerReadFloat(parcel, "Config:/VersionConfig", &dVersion);

Perl Example:
$version = WebPerl::ReadFloat($parcel, 'Config:/VersionConfig');

Reads the indicated variable and converts it (if necessary) into a text buffer.

C Example:
rc = ServerReadText(parcel, "Config:/ConfigFile", buffer, sizeof(buffer));

Perl Example:
$file = WebPerl::ReadText($parcel, 'Config:/ConfigFile');

ServerReadBinary>

Reads the indicated variable and converts it (if necessary) into an unformatted binary buffer.

C Example:
rc = ServerReadBinary(parcel, "Request:/ArgumentText", buffer, sizeof(buffer));

Perl Example:
$URL_data = WebPerl::ReadBinary($parcel, 'Request:/ArgumentText');

Flushes the current contents of the indicated variable. If the variable is connected to a socket, its contents are sent by TCP/IP. If the variable is connected to a file, its contents are recorded to disk. If the variable is simply a memory variable, it is emptied.

C Example:
rc = ServerFlush(parcel, "Request:/Result");

Perl Example:
WebPerl::Flush($parcel, 'Request:/Result');

Writes the integer value to the indicated variable, performing datatype conversions if necessary.

C Example:
rc = ServerWriteInteger(parcel, "Request:/StatusCode", 401);

Perl Example:
WebPerl::WriteInteger($parcel, 'Request:/StatusCode', 401);

Writes the double precision floating point value to the indicated variable, performing datatype conversions if necessary.

Writes the text buffer to the indicated variable, performing datatype conversions if necessary.

C Example:
rc = ServerWriteText(parcel, "Request:/StatusText", "Authorisation is Required");

Perl Example:
WebPerl::WriteText($parcel, 'Request:/StatusText', 'Authorisation is Required');

Writes the binary buffer to the indicated variable, performing datatype conversions if necessary.

C Example:
rc = ServerWriteBinary(parcel, "Request:/Result", buffer, cbResult);

Perl Example:
WebPerl::WriteBinary($parcel, 'Request:/Result', $buffer);

Appends a text buffer to the existing content of the indicated variable, performing datatype conversions if necessary.

C Example:
rc = ServerAppendText(parcel, "Request:/Result", "All Rights Reserved");

Perl Example:
WebPerl::AppendText($parcel, 'Request:/Result', 'All Rights Reserved');

Appends a binary buffer to the existing content of the indicated variable, performing datatype conversions if necessary.

C Example:
rc = ServerAppendText(parcel, "Request:/Result", buffer, cbExtra);

(Perl only) Appends the provided text to the current output object (which is the HTML document when running the HTTP protocol, and is named "Request:/Result"). It is a shortcut function for porting old CGI scripts: simply replace all occurrences of "print" with "WebPerl::Print".

Perl Example:
WebPerl::Print 'All Rights Reserved';

Creates a new integer variable, initialised to a given value, and given a specified name within the indicated variable directory.

C Example:
rc = ServerFind(parcel, "Request:/Argument", &handleArgument);
rc = ServerNewInteger(handleArgument, "MyNewFormVariable", 100);

Perl Example:
$handleArgument = WebPerl::Find($parcel, 'Request:/Argument');
WebPerl::NewInteger($handleArgument, 'MyNewFormVariable', 100);

Creates a new floating point variable, initialised to a given value, and given a specified name within the indicated variable directory.

C Example:
rc = ServerFind(parcel, "Request:/Argument", &handleArgument);
rc = ServerNewFloat(handleArgument, "MyNewFormVariable", 3.1415);

Creates a new text variable, initialised to a given value, and given a specified name within the indicated variable directory.

C Example:
rc = ServerFind(parcel, "Request:/Argument", &handleArgument);
rc = ServerNewText(handleArgument, "MyNewFormVariable", "MyForm");

Perl Example:
$handleArgument = WebPerl::Find($parcel, 'Request:/Argument');
WebPerl::NewText($handleArgument, 'MyNewFormVariable', 'MyForm');

Creates a new binary variable, initialised to a given value, and given a specified name within the indicated variable directory.

C Example:
rc = ServerFind(parcel, "Request:/Argument", &handleArgument);
rc = ServerNewBinary(handleArgument, "MyNewFormVariable", buffer, cbData);

Creates a new list variable, given a specified name within the indicated variable directory. A list variable is the same as a "variable directory" - it is simply a variable that can contain other variables (of any type, including nested lists).

C Example:
rc = ServerGetConfig(parcel, &handleConfig);
rc = ServerNewList(handleConfig, "ClientList");

Creates a new semaphore, given a specified name within the indicated variable directory. A semaphore variable is used to control the execution of multiple simultaneous requests. PowerWeb Server++ is fully multi-thread safe and re-entrant, but if you write your own API Extensions you need to ensure that your own code is similarly protected. Semaphores allow you to manage contention for a shared resource.

An example is the use of the DB/2 Rexx interface which uses global variables to access DB/2 and is therefore not multi-thread safe. Note that in general both Rexx and C will be multi-thread safe except in the case of global status variables or files shared among multiple invocations of the same code by simultaneous requests.

C Example:
rc = ServerGetConfig(parcel, &handleConfig);
rc = ServerNewSemaphore(handleConfig, "DB2Rexx");

Semaphore Semantics:

Release: use ServerWriteInteger() with the value -1.
Request, no timeout: use ServerWriteInteger() with the value 0.
Request, with timeout: use ServerWriteInteger() with the number of milliseconds to wait before giving up.
Query Number of Locks: use ServerReadInteger()

If the semaphore is in use by another process or thread and your timeout was exceeded, then ERR_BUSY is returned (C and Perl APIs only - in Rexx, error number 40 is raised). Remember to ALWAYS release any semaphore you successfully request, otherwise subsequent requests will fail. This often means you must write error handling code in your API Extension to ensure that the semaphore is released even when errors occur.

C Example of Requesting with 5 second timeout:
rc = ServerWriteInteger(parcel, "Config:/DB2Rexx", 5000);

Rexx Example of Requesting with 5 second timeout:
call ServerWriteText parcel, "Config:/DB2Rexx", "5000"

To make writing your API Extensions simpler, PowerWeb comes pre-configured with a semaphore you can use for your applications. It is named "Config:/Semaphore/Global". This semaphore is automatically created for you on startup and is automatically closed when PowerWeb quits. See the sample code for the UserAuthentication hook to see how to use the variable. If you need more than one semaphore, we suggest you create your own ones in the same "Config:/Semaphore" directory.

Deletes an existing WebObject. You must have delete permission or the request will be refused. All HTTP form arguments and WebObjects that you create yourself have delete permission.

C Example:
rc = ServerFind(parcel, "Request:/Argument/Unwanted", &handle);
rc = ServerDelete(handle);

Returns the handle of the parent of the indicated variable.

C Example:
rc = ServerParent(handleVariable, &handleParent);

Perl Example:
$handleParent = WebPerl::Parent($handleVariable);

Returns the handle of the first child of the indicated variable.

C Example:
rc = ServerChild(handleVariable, &handleChild);

Perl Example:
$handleChild = WebPerl::Child($handleVariable);

Returns the handle of the next sibling of the indicated variable. Commonly used in conjunction with ServerChild in order to walk through the entire tree of variables.

C Example:
rc = ServerChild(handleVariable, &handleChild);
rc = ServerSibling(handleChild, &handleNext);

Perl Example:
$handleChild = WebPerl::Child($handleVariable);
if ($handleChild) { $handleNext = WebPerl::Sibling($handleChild); }

Interprets a block of WebMacro code, appending the result to the current "Request:/Result" variable. Used in conjunction with the "into=" attribute of WebMacros, you can redirect the result into another PowerWeb variable and further manipulate it instead of sending it directly to the standard result variable.

C Example:
rc = ServerInterpret(parcel, "<!--#concat var=Config:/Servers into=ServerList -->");

(Perl only) Returns the error result of the most recently called WebPerl function.

Perl Example:
$rc = WebPerl::GetError();

(Perl only) Used with Embedded Perl to get access to the PowerWeb "parcel" magic cookie which is used within many other function calls. Normally Perl functions within Perl packages are passed the "parcel" as their first argument.

Perl Example:
$parcel = WebPerl::GetParcel();

(Perl only) Returns the function name specified within the URL or exec WebMacro. This is useful for old-style Perl modules which are not packages.

Perl Example:
$function = WebPerl::GetFunction();