Functions

OAEXTERNAL

oaexternal allows external routines located on the server to be executed from both server and client applications. It also permits Omnidex Client applications to indirectly call such OmniAccess routines like oainsertindex, that are not directly available to Omnidex Client applications.

The external routines are usually written in a language like C and must be located in a shared library (.dll on Windows and .sl or .so on Unix) in order to be dynamically loaded.

One purpose for using oaexternal might be to help decrease the costs incurred by client/server applications. Every time a client application makes a request to the server, the costs incurred for this request include not only the server processing time, but also the io time required to send the request and receive the results across the network. This cost for a single request may not be significant, but can quickly add up for multiple requests.

In a select and fetch application, for example, it might be beneficial to write an external routine that, after a select has been processed, fetches the results and places them into a buffer to be returned to the client application. This reduces the network traffic from multiple calls to oafetch, to one call to oaexternal. The server processing time is unchanged, but the io time is reduced significantly.

This is a very simplified example but sufficiently demonstrates the effectiveness of using oaexternal.

Routines written for oaexternal can call other routines including OmniAccess routines. The return value of the routines called by this routine, must be defined as a 32-bit integer. In C, the routine’s return value is defined as follows:

int32 routine (void*input, int32 input_length, void*output, int32*output_length)

The external routines called through oaexternal must be able to create an input buffer based on the value in input_length, and to reference that input when executing. If they return data they should also be able to allocate enough memory, as specified in output_length, to contain that data. The routine can change the length of the output buffer as described in “Dynamically specifying the output_length”.

Dynamically Specifying the output_length

The output_length must be declared to be greater than or equal to the length of the data returned from the routine specified in the routine parameter. Output_length must reflect enough memory to hold the data returned to the external routine. If output_length is too small, the returned data may overwrite other buffers in the routine. If output_length is too big, it creates an unnecessary burden on the network. If the executed routine without returning anything, output_length can contain a null.

To dynamically specify the output_length of the information returned to the local, or client, processor, reference output_length as a returned value in the external routine named in the routine parameter. This can help reduce network traffic if the length of the value returned is less than the length originally passed for output_length. Dynamically specifying output_length shrinks the returned output buffer and results in less network traffic.

Resolving Calls to External Routines

When linking programs, the libraries must be referenced in the order that they are accessed. For example, if a program calls oaexternal, to call a routine that resides in a library called lda, which calls routines in the locic and lora libraries. When linking the program, reference the libraries in the order that they are referenced, as follows:

ld myprog -L -loa -lda -locic -lora

The order in which routines call other routines also affects how a dynamic link path is specified on MPE. For example, if an application calls oaexternal to call a routine that resides in MYXL.PUB.MYACCT, the external routine must be linked, using the Link Editor, to the libraries it needs to resolve in the order they are used. To call an external routine called "updtidx" that resides in OBJ.MYACCT, use Link Editor like this:

:RUN LINKEDIT.PUB.SYS

HP Link Editor/iX (HP30315A.05.06) Copyright Hewlett-Packard Co 1986

LinkEd> copyxl from=xloa.oa.disc;to=xlomnidx.pub.sys

1 OBJECT FILE HAS BEEN COPIED.

LinkEd> addxl from=updtidx.obj.myacct;to=xlomnidx.pub.sys;module=updtidx

1 OBJECT FILE HAS BEEN ADDED.

LinkEd> exit

oaexternal does not support archived libraries. The oaexternal routine must be in a shared library in order to be dynamically loaded.

Syntax

oaexternal (instance, options, status, node, library_name, routine_name,
input, input_length, output, output_length)

instance -- Identifies a unique connection to a server environment catalog previously established by oaconnect. Instance is a 32-bit signed integer passed by value.

options -- Reserved for future use. Must contain a null or a semicolon passed by reference.

status -- Indicates the success or failure of the oaexternal routine. A zero in status word 1 means a successful call to oaexternal. The status structure is passed by reference and contains fourteen 32-bit signed integers, followed by a 36 character buffer.

node -- Is reserved when oaexternal is used in a server-based application and must contain only a semicolon or null terminator. However, when a client application calls oaexternal, node must contain the server object name as declared in the Client Data Source file (terminated by a semicolon or null). In both cases, oaexternal executes the routine on the server.

library -- Is a character value passed by reference, not longer than 256 bytes including a semicolon or null terminator. It specifies the name of the library that contains the specified routine. (MPE/iX and UNIX only)

routine -- Is a character value passed by reference, not longer than 256 bytes including a semicolon or null terminator. It specifies the requested routine.

inputparms -- Is a character array passed by reference. It cannot exceed the maximum length allowed by the server’s operating system or Windows, whichever is less. It contains any input parameters required by the specified routine. Separate multiple parameters with commas and terminate the value with a semicolon or null character.

inputparmslength -- Is a 32-bit integer value, passed by value. It specifies the length in bytes of the input parameter.

outputparms -- Is a character array passed by reference. It cannot exceed the maximum length allowed by the server’s operating system or Windows, whichever is less. It contains any output parameters required by the specified routine. Separate multiple parameters with commas and terminate the value with a semicolon or null character.

outputparmslength -- Is a 32-bit integer value, passed by value, that allocates memory in bytes for the output parameter. You can dynamically change this value based on what the external routine actually returns, as discussed in “Dynamically specifying the output_length”.

Options

There are currently no options available for oaexternal. Support was added for future enhancements.

Example

Top