Using the Caché Callout Gateway
Special Considerations for OpenVMS
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

You can call OpenVMS system services with $ZF. You define an interface to each non-Caché ObjectScript routine in a file named CZF.M64. You can also use $ZF to call OpenVMS System Service Routines, invoke DCL Command Procedures, or other high-level language routines.

This chapter discusses the following topics:
Using CZF.M64
The preferred language for writing Callout code is C (creating a CZF.C file, as described in Creating a Caché Callout Library), but it is also possible to use a macro file (CZF.M64). Use CZF.C if you have a C compiler; otherwise, use CZF.M64. You cannot use both.
When using the CZF.M64 file, you enter only ZFENTRY statements between the .SHOW and .END commands. The statements must have the following format:
   ZFENTRY CALLNAME=name,LINKNAME=fname,ARGS=atype,PRIVS=priv
Although the calling format is different, this is essentially the same as the ZFENTRY statement used in C programs (see Creating a ZFEntry Table).
Assembling CZF.M64
To assemble CZF.M64, issue the following command from the DCL prompt:
$ MAC /ALPHA CZF.M64
Using ZFPRIV to Elevate the Privilege Level
ZFENTRY statements run at the privilege level of the calling process. If you want it to have all privileges except the SHARE privilege, you can describe the external function with a ZFPRIV statement. A ZFPRIV statement has the same format as a ZFENTRY statement except for the statement name and the addition of a privileges argument at the end of the argument list, as shown below:
 ZFPRIV("name","argtypes",entrypoint,privileges)
The privileges argument can be either of the following:
To allow czf.c files to be moved unchanged between OpenVMS and other operating systems, these macros have the following effects:
71 Using the V Linkage for System Services
To accommodate calling OpenVMS system services and library routines, you can pass with an OpenVMS descriptor using the "v" linkage type.
struct dsc$descriptor s * v V OpenVMS only: used when calling OpenVMS system services.
In this example we will expose the OpenVMS function LIB$TRIM_FILESPEC to Caché ObjectScript. From ObjectScript, this call will be available:
 SET newfilespec=$ZF("TRIM FILESPEC",oldfilespec,width)
The CZF interface passes 32 actual parameters to all functions that it calls. If you provide less that 32 actual parameters, NULL is passed for those parameters. Since LIB$TRIM_FILESPEC, like many library and system functions, counts the number of actual parameters, it is necessary to declare a trivial wrapper function:
#ifdef __VMS
  ZFENTRY("TRIM_FILESPEC","viV",trim_filespec)
#endif
where the wrapper function is:
function trim_filespec
#ifdef __VMS
int trim_filespec(struct dsc$descriptor_s*oldfilespec,int width,struct dsc$descriptor_s*newfilespec){
  short int resultwidth;
  int s;

  if(width> ZFString)return ZF_FAILURE;
  s= LIB$TRIM_FILESPEC(oldfilespec,newfilespec,&width,&resultwidth);
  newfilespec->dsc$w_length= resultwidth;
  return s;
}
#endif
$ZF Function Calls for DSM
This section describes Caché-supplied (intrinsic) functions that can be supplied as arguments to the $ZF function to emulate DSM VMS System Service Zcall functions. These functions are contained in the standard CZF.EXE Callout image. See Creating a Custom CZF.EXE File in OpenVMS for information on customizing this image.
The following intrinsic functions are discussed:
$ZF Intrinsic Functions
All of the intrinsic functions can be called by $ZF, specifying only the function name followed by any other parameters. The following example shows GETUAI used as a function:
    SET x = $ZF("GETUAI","FRED","USERNAME")
Note:
The function names are shown here in all uppercase letters, but they are not actually case-sensitive.
GETJPI
Returns job and process information.
   SET x = $ZF("GETJPI",pid,item)
   SET x = $ZF("GETJPI",,item,procname)
Parameters:
Item Codes for GETJPI
ACCOUNT DFPFC IMAGECOUNT PHDFLAGS TMBU
APTCNT DFWSCNT IMAGNAME PID TQCNT
ASTACT DIOCNT IMAGPRIV PPGCNT TQLM
ASTCNT DIOLM JOBPRCCNT PRCCNT TT_ACCPORNAM
ASTEN DIRIO JOBTYPE PRCLM TT_PHYDEVNAM
ASTLM EFCS LOGINTIM PRCNAM UAF_FLAGS
AUTHPRI EFCU MASTER_PID PRI UIC
AUTHPRIV EFWM MAXDETACH PRIB USERNAME
BIOCNT ENQCNT MAXJOBS PROC_INDEX VIRTPEAK
BIOLM ENQLM MEM PROCPRIV VOLUMES
BUFIO EXCVEC MODE SCHED_POLICY VP_CONSUMER
BYTCNT FAST_VP_SWITCH MSGMASK SHRFILLM VP_CPUTIM
BYTLM FILCNT NODENAME SITESPEC WSAUTH
CLINAME FILLM NODE_CSID SLOW_VP_SWITCH WSAUTHEXT
CPU_ID FINALEXC NOD_VERSION STATE WSEXTENT
CPULIM FREP0VA OWNER STS WSPEAK
CPUTIM FREP1VA PAGEFLTS STS2 WSQUOTA
CREPRC FREPTECNT PAGFILCNT SWPFILLOC WSSIZE
FLAGS GPGCNT PAGFILLOC TABLENAME  
CURPRIV GRP PGFLQUOTA TERMINAL  
GETDVI
Returns device characteristics.
SET x = $ZF("GETDVI",devname,item,flag)
Parameters:
Item Codes for GETDVI
ACPTYPE EXISTS PID TT_AUTOBAUD TT_MODHANGUP
ALL FOD RCK TT_AVO TT_NOBRDCST
ALLDEVNAM FOR RCT TT_BLOCK TT_NOECHO
ALLOCLASS FREEBLOCKS REC TT_BRDCSTMBX TT_NOTYPEAHD
ALT_HOST_AVAIL FULLDEVNAM RECSIZ TT_CRFILL TT_OPER
ALT_HOST_NAME GEN REFCNT TT_DECCRT TT_PAGE
ALT_HOST_TYPE HOST_AVAIL REMOTE_DEVICE TT_DECCRT2 TT_PASTHRU
AVL HOST_COUNT RND TT_DIALUP TT_PHYDEVNAM
CCL HOST_NAME ROOTDEVNAM TT_DISCONNECT TT_PRINTER
CLUSTER HOST_TYPE RTM TT_DMA TT_READSYNC
CONCEALED IDV SDI TT_DRCS TT_REGIS
CYLINDERS LOCKID SECTORS TT_EDIT TT_REMOTE
DEVBUFSIZ LOGVOLNAM SERIALNUM TT_EDITING TT_SCOPE
DEVCHAR MAXBLOCK SERVED_DEVICE TT_EIGHTBIT TT_SECURE
DEVCHAR2 MAXFILES SHR TT_ESCAPE TT_SETSPEED
DEVCLASS MBX SPL TT_FALLBACK TT_SIXEL
DEVDEPEND MEDIA_ID SPLDEVNAM TT_HALFDUP TT_SYSPWD
DEVDEPEND2 MEDIA_NAME SQD TT_HANGUP TT_TTSYNC
DEVLOCKNAM MEDIA_TYPE STS TT_HOSTSYNC TT_WRAP
DEVNAM MNT SWL TT_INSERT UNIT
DEVSTS MOUNTCNT TRACKS TT_LFFILL VOLCOUNT
DEVTYPE NET TRANSCNT TT_LOCALECHO VOLNAM
DIR NEXTDEVNAM TRM TT_LOWER VOLNUMBER
DMT ODV TT_ACCPORNAM TT_MBXDSABL VOLSETMEM
DUA OPCNT TT_ALTYPEAHD TT_MECHFORM VPROT
ELG OPR TT_ANSICRT TT_MECHTAB WCK
ERRCNT OWNUIC TT_APP_KEYPAD TT_MODEM  
GETSYI
Returns system information.
SET x = $ZF("GETSYI",item,csid[,nodename])
Parameters:
Item Codes for GETSYI
ACTIVECPU_CNT CLUSTER_FTIME FREE_GBLPAGES PAGEFILE_FREE PQL_MFILLM
ARCHFLAG CLUSTER_MEMBER FREE_GBLSECTS PAGEFILE_PAGE PQL_MENQLM
ARCH_NAME CLUSTER_NODES GBLPAGES PQL_DWSDEFAULT SCSNODE
ARCH_TYPE CLUSTER_QUORUM GBLPAGFIL PQL_DWSEXTENT SPTREQ
AVAILCPU_CNT CPU GBLSECTIONS PQL_DWSQUOTA SRPCOUNTV
BALSETCNT CONTIG_GBLPAGES LOCKIDTBL PQL_MWSDEFAULT SWAPFILE_FREE
BJOBLIM CPUTYPE LOCKIDTBL_MAX PQL_MWSEXTENT SWAPFILE_PAGE
BOOTTIME DECIMAL_EMULATED MAXPROCESSCNT PQL_MWSQUOTA VERSION
CHARACTER_EMULATED D_FLOAT_EMULATED MAXSYSGROUP PQL_MASTLM VIRTUALPAGECNT
CLUSTER_EVOTES HW_MODEL NODENAME PQL_MBYTLM WSMAX
CLUSTER_FSYSID HW_NAME NODE_CSID PQL_MDIOLM  
SETSYM
Sets a DCL symbol to a value. This DCL symbol can be local or global. SETSYM returns the null string.
SET x = $ZF("SETSYM",symbol,value,flag)
Parameters:
GETSYM
Returns the value of a specified DCL symbol. This DCL symbol can be local or global. You can use a flag value of 1 to determine the symbol type. DCL values are set using the SETSYM function.
SET x = $ZF("GETSYM",symbol[,flag])
Parameters:
DELSYM
Deletes the value of a specified DCL symbol. This DCL symbol can be local or global. DCL values are set using the SETSYM function.
SET x = $ZF("DELSYM",symbol,flag)
Parameters:
CRELOG
Creates a logical name in the specified logical name table with the specified mode. Defaults are type=USER mode and table=process logical name table. CRELOG returns a null string.
SET x = $ZF("CRELOG",logname,value[,type[,table]])
Parameters:
The available type values are:
TRNLNM
Translates a logical name and returns the equivalence name string or the requested attributes. TRNLNM returns the null string if no match is found.
SET x = $ZF("TRNLNM",logname,table,index,acmode,trans,item)
Parameters:
DELLOG
Deletes a logical name in the specified logical name table.
SET x = $ZF("DELLOG",logname,type,table)
Parameters:
GETUAI
Returns values for authorization parameters of a specific OpenVMS account.
SET x = $ZF("GETUAI",account,item)
Parameters:
Item Codes for GETUAI
ACCOUNT DFWSCNT LASTLOGIN_N PGFLQUOTA UIC
ASTLM DIOLM LGICMD PRCCNT USERNAME
BIOLM ENQLM MAXACCTJOBS PRI WSEXTENT
BYTLM FILLM MAXDETACH PRIV WSQUOTA
DEFDEV FLAGS MAXJOBS QUEPRI  
DEFDIR JTQUOTA OWNER SHRFILLM  
DEF_PRIV LASTLOGIN_I PBYTLM TQCNT  
GETMSG
Returns the message text that corresponds to the specified status code.
SET x = $ZF("GETMSG",code)
Parameter:
SETPRN
Sets the name of the calling process to the specified OpenVMS process name.
SET x = $ZF("SETPRN",pname)
Parameter:
SETPRI
Sets the base priority of the specified process. The process must be running CACHE image.
SET x = $ZF("SETPRI",pri,pid)
Parameters:
OPCOM
Sends the specified message to the operator terminal(s). It returns a null string.
SET x = $ZF("OPCOM",msg)
Parameter:
MOUNT
Mounts the specified device. This function calls LIB$SPAWN to issue the DCL command MOUNT.
SET x = $ZF("MOUNT",devnam,label,options,lognam)
Parameters:
DISMOUNT
Dismounts the specified device. This function calls LIB$SPAWN to issue the DCL command DISMOUNT.
SET x = $ZF("DISMOUNT",devnam,options)
Parameters:
DIRECTORY
Returns the current OpenVMS default directory, and optionally sets the OpenVMS default directory to the specified directory.
SET x = $ZF("DIRECTORY",dir)
Parameter:
PARSE
Parses the specified file name and returns a parsed file name. PARSE calls the RMS $PARSE service.
SET x = $ZF("PARSE",filename,defname,relname,keyword,flag)
Parameters:
GETFILE
Teturns information about the specified file. This function emulates the F$FILE_ATTRIBUTES lexical function, using the same keywords. GETFILE returns the UIC in standard OpenVMS format, and returns TRUE or FALSE as 1 or 0.
SET x = $ZF("GETFILE",filename,keyword)
Parameters:
Keywords for GETFILE
ALQ DEQ GBC NOK RVN
BDT DID IBS ORG SIZ
BKS DVI LRL PRO UIC
BLS EDT LVL PVN WCK
CBT EOF MBM RAT  
CDT FID MRN RCK  
CTG FSZ MRS RDT  
DBS GRP NOA RFM