$ZF = $ZF

Call a non-CacheObjectScript program or function from a CacheObjectScript routine.

The outline

$ZF("function_name",args)
Copy the code

parameter

  • Function_name Specifies the name of the function to call.
  • Args Optional – A set of parameter values passed to a function.

describe

The various forms of the $ZF function make it possible to call non-ObjectScript programs (such as shell or operating system commands) or functions from ObjectScript routines. You can define interfaces or links to functions written in Cache in other languages and call them from ObjectScript routines using $ZF.

$ZF can also be used for:

  • To generate a child process to execute a program or command:$ZF(-100).
  • Load a dynamic link library (DLL) and then execute functions from that library:$ZF (- 3).$ZF (-- 4).$ZF (-- 5).$ZF (-- 6).

These implementations of $ZF take a negative number as their first argument. They are described in their respective reference pages.

parameter

function_name

The name of the function to be called is quoted, or negative.

args

The args argument is of the form arg1, arg2, arg3… Argn. Arguments can include items such as a description of how to pass the argument and the entry point of the C function to be called.

Pay attention to

with$ZFInvoke UNIX® system services

Cache supports error checking for use with ZF’s UNIX® system calls. These calls make it possible to check for asynchronous events and set up alarm handlers in ‘ZF. By using these UNIX® functions, you can distinguish between actual errors, interrupts, and calls that should be restarted.

Function declarations are included in cdzf.h and are described in the following table:

The statement The target Pay attention to
int sigrtclr(); Clear the retry flag. usesigrtchk()It should be called once before
int dzfalarm(); Create a new SIGALRM handler. In the input$ZFThe previous handler is saved automatically. When you exit, it will automatically resume. The user program shall not alter the handling of any other signal.
int sigrtchk(); Check for asynchronous events. Should be called whenever one of the following system calls fails:open().close().read().write().ioctl().pause(), any calls that fail when the process receives a signal. It returns a code indicating the action the user should take: -1 = No signal. Check I/O errors. See the contents of the errno variable. 0 = other signals. Restart operations from the breakpoint. 1 = SIGINT /. Use SIGTERM “Return 0” from$ZFTo exit. The system captures these signals appropriately.

In a typical $ZF function used to control some devices, code these signals appropriately.

  IF ((fd = open(DEV_NAME, DEV_MODE)) < 0) {; Set some flags ; Call zferror ;return 0;
  }
Copy the code

If the process receives a signal, the open system call may fail. Normally, this is not an error and the operation should be restarted. However, depending on the signal, other measures may be taken. So, to consider all possibilities, consider using the following C code:

sigrtclr();
   WHILE (TRUE) {
      IF (sigrtchk() == 1) { return 1 or 0; }
      IF ((fd = open(DEV_NAME, DEV_MODE)) < 0) {
         switch (sigrtchk()) {
         case - 1:
           /* Real device error */; Set the flag Call zferrorreturn 0;
         case 0:
           /* A harmless signal is received. Start over. * /; To continue;case 1:
           /* Attempted to terminate the JOB. * /
           Do cleanup work
           return 1 or 0;
         }
      }
      ELSE { break; }
   /* The code to handle normal cases: */
   /* open() system call successful */
Copy the code

Remember that you cannot set up any signal handlers except through DZfalarm ().

Converts strings between encoding systems

The Cache supports input/output conversions through the $ZF parameter type t (or t), which can be specified in the following format:

Argument Purpose
t Specifies the current process I/O conversion object.
t// Specifies the default process I/O transformation table name.
t/name/ Specify a specific I/O transformation table name.

$ZF passes the converted string to an external procedure by placing a count byte string in the following C structure:

typedef struct zarray {
    unsigned short len;
    unsigned char data[1]; /* 1 is a dummy value */
    } *ZARRAYP;
Copy the code

This is also the structure used for b (or B) parameter types.

The following $ZF sample functions perform a round-trip conversion:

#include cdzf.h
extern    int trantest(a);
ZFBEGIN
ZFENTRY("TRANTEST"."t/SJIS/ T/SJIS/",trantest)

ZFEND

int trantest(inbuf,outbuf);

ZARRAYP inbuf;         /* buffer containing the string */ converted from internal Cache encoding to SJIS encoding before being passed to this function
ZARRAYP outbuf;        /* A buffer containing a sJIS-encoded string that is converted back to the internal Cache encoding */ before passing it back to the Cache environment
{
  int  i;
  /* Copies one byte at a time from the input parameter buffer to the output parameter buffer */

  for (i = 0; i < inbuf->len; i++)
     outbuf->data[i] = inbuf->data[i];

  /* Sets the number of bytes of data in the output parameter buffer n */
       outbuf->len = inbuf->len;

  return 0;  /* Return success */
}

Copy the code

Note: Conceptually, data flows in and out of $ZF external processes as if the external processes were devices. The output component of the I/O transformation is used to pass data to external procedures as it “leaves” the Cache environment. The input component of the I/O transformation is used for data received from external procedures as it is “entering” the Cache environment.

If the output component of an I/O transform is not defined and the application tries to use the I/O transform to pass anything but an empty string, the Cache returns an error because it does not know how to transform the data.

If the input component of an I/O conversion is not defined and the parameter of the type string associates the I/O conversion with the $ZF output parameter, the Cache returns an error because output parameters with undefined conversions are purposeless.

A zero-terminated and counted Unicode string

The $ZF function supports zero-ending Unicode strings and counting Unicode string parameter types. These features are supported even in Cache versions that do not use Unicode characters internally.

Parameter types for zero-terminated Unicode strings and counting Unicode strings have the following code:

Argument Purpose
w Pointer to a zero-terminated Unicode string.
s Pointer to a counting Unicode string.

For both parameter types, the C data type of Unicode characters is an unsigned abbreviation. A pointer to a zero-ending Unicode string is declared as follows:

unsigned short *p;
Copy the code

Pointers to counted Unicode strings are declared as Pointers to the following C structures:

typedef struct zwarray {
    unsigned short len;
    unsigned short data[1]; /* 1 is a dummy value */
    } *ZWARRAYP;
Copy the code

Such as:

ZWARRAYP *p;
Copy the code

The len field contains the length of the Unicode character array.

The data field contains characters in the Unicode string that count. The maximum size of a Unicode string is the maximum size of a $ZF string, which is an updatable configuration parameter and defaults to 32767.

Each Unicode character is two bytes long. This is important to consider when declaring Unicode strings as output parameters, because the Cache reserves space for the longest string that can be returned. Using the default string size, the total memory consumption for a single Unicode string parameter is calculated as follows:

Maximum 32767 characters * 2 bytes per character = total 65534 bytes.

This is close to the default maximum memory region allocated for all $ZF parameters, which is 67,584. This maximum $ZF heap area is also an updatable configuration parameter.

The error message

$ZF emits an error when the $ZF heap area is used up. $ZF emits an error when the $ZF string stack is exhausted. When $ZF cannot allocate a partner block, it issues a

error.

Execute from child processes and DLLS

The $ZF function can take a negative number as its first argument. These negative numbers specify the functionality that supports generated child processes and dynamic link libraries (DLLS). Each of these $ZF functions is described in a separate reference page.