2 Designing and Writing LUA Applications

2.1.1 Function Call

           void RUI(verb)
           LUA_VERB_RECORD * verb;

2.1.2 Supplied Parameters

Supplied parameter is:

verb

Pointer to a Verb Control Block (VCB) that contains the parameters for the verb being issued. The VCB structure is defined in the LUA header file /usr/include/sna/lua_c.h, and is described in LUA Verbs.

Note

The LUA VCB contains many parameters marked as reserved; some of these are used internally by the SNAP-IX software, and others are not used in this version but may be used in future versions. Your application must not attempt to access any of these reserved parameters; instead, it must set the entire contents of the VCB to zero to ensure that all of these parameters are zero, before it sets other parameters that are used by the verb. This ensures that SNAP-IX will not misinterpret any of its internally-used parameters, and also that your application will continue to work with future SNAP-IX versions in which these parameters may be used to provide new functions.

To set the VCB contents to zero, use memset:

memset(vcb, 0, sizeof(vcb));

2.1.3 Returned Values

The entry point does not return a value. When the call returns, the application can examine the parameters in the VCB to determine whether the verb has completed synchronously or will complete asynchronously; for more information, see Usage.

2.1.4 Usage

Sometimes LUA is able to complete all the processing for a verb as soon as it is issued. When this happens, the verb returns synchronously; the primary return code is set to a value other than LUA_IN_PROGRESS, and the lua_flag2.async bit is set to 0 (zero). (For information about these returned parameters, see LUA Verbs.)

At other times, LUA must wait for information from the remote LU or from the node before it can complete the verb. In this case, the verb returns asynchronously; the primary return code is set to LUA_IN_PROGRESS , and the lua_flag2.async bit is set to 1. The application can now perform other processing, or wait for notification from LUA that the verb has completed. LUA issues this notification by setting the primary return code to its final value, leaving lua_flag2.async set to 1.

As part of the supplied VCB, the application supplies a pointer to a callback routine (in the lua_post_handle parameter). If the verb completes synchronously, LUA does not call the callback routine. If the verb completes asynchronously, LUA indicates the verb completion by calling the callback routine with one parameter-a pointer to the original verb control block (VCB). For more information, see Callback Routine for Asynchronous Verb Completion.

It is not possible for an application to predict whether a particular verb will complete synchronously or asynchronously.

2.1.5 Callback Routine for Asynchronous Verb Completion

To enable an LUA verb to complete asynchronously, the application must supply a pointer to a callback routine. This section describes how SNAP-IX uses this routine, and the functions that it must perform.

          void callback (verb)
          LUA_VERB_RECORD * verb;
          {     .
                .
          }