|
The server first checks to see
if the database number is valid and active.
The server program then
checks to see if the procedure name exists in the master
dictionary or Voc file of the server account. It checks to see
if the first character of the first attribute is a V or P
(cannot be part of a PQ, however).
The program makes an indirect
CALL of the procedure (i.e. calling @Procedure). The arguments
it passes are:
DBID - The database id which
references a given Pick Account. This value is passed as the
Database handle by the client.
ARGS - A multi-valued list of
arguments passed by the client. This list of values is
optional and can be a null string, or the arguments needed by
the procedure being called.
RTNCD - This is a return
argument supplied by the called procedure upon completion. If
this value is the number one (1), the procedure has indicated
that it has successfully been executed. A value of zero
indicates the process has failed in some way. Error messages
associated with the failure can be passed back through the
RESULT parameter. The server program will pass this argument
value back as the return code.
RESULT - This is a return
argument supplied by the called procedure upon completion. It
can either have the results of the procedure or a set of error
messages that the server program will pass back to the client
program. These results can be a single value, multiple values,
or a set of records.
Programmer Notes:
When a client process
initiates the server, the server (VSSERVER) will remain logged
in as long as that process is running on the client or a Close
Database and Close Connection message is sent from the client.
That means, of course, all of the common variables will remain
active for the duration of the process (a list of the servers
common variables will be found in the INCLUDES file in the
item VSCOMMON). Therefore, if the database system the
programmer is on supports Named Common, the programmer will
have access to those variables in the named common in their
procedure(s) on the server during the entire execution of the
client process.
The stored procedure may also
call its on procedures, which in turn, may call other
procedures. The programmer must remember that all files and
procedures handled within their stored procedure program must
be defined and/or compiled in the Server Account (MVSERVER).
File references used in a
called stored procedure can use a special subroutine available
on the MVSERVER account. This is the VSOPEN subroutine and
provides to a called subroutine program, a file variable that
can be used for file processing based on the VSDATABASE
mapping and resulting q-pointer generated by the mapping
process. The VSOPEN program has four arguments that must be
passed when calling this routine. The calling syntax is as
follows:
CALL
VSOPEN(DBID, FILE.NAME, TYPE, FILE.REF, RTN)
Where the DBID is the Database
handle passed to your stored procedure in your first argument.
The FILE.NAME variable is a string containing the name of the
file you want open. The TYPE variable has either the value 0
or 1. A 0 value represents the data level of the file, a 1
value represents the dictionary level of the file. The
FILE.REF variable is the Pick file reference variable,
returned from the VSOPEN routine. Once returned to your stored
procedure program, you can use this file reference variable as
you could any file variable that you opened with the standard
Pick Basic OPEN statement. The RTN value is a flag indicating
if the VSOPEN routine was successful in returning a valid file
reference for the supplied file name. If RTN has a value of 1,
the execution was successful and the FILE.REF argument has a
valid file reference variable. If RTN has a zero value, the
VSOPEN call failed for some reason, usually due to the
supplied file name not being mapped.
Another important point to
remember is that any Pick program routine used as a stored
procedure cannot perform any standard input/output statements,
as this will interrupt the normal client/server protocol flow
between the server and the client program.
More information on stored
procedures can be found later in this document
Note: The User Results
parameter should have “substitute” Record Marks Char(249)
delimiting records, and Attribute marks Char(254) delimiting
fields. When working at the client side with dynamic array
records that are sent or received from the Vantage Server, you
must use the “normal” Record or Row mark (Char 255) to
separate records and the Attribute mark (Char 254) to separate
fields. The Channel database object HostSendMessage method, which handles all communication
with the Vpmv20.dll file, converts the delimiters before
passing them to and from the Vpmv20 DLL functions.
A Record mark (Char 254) is converted to the needed
“substitute” Record Mark Char(249) when going to the Pick
Host and is reversed when data is going to the client.
Therefore, in your client code, when dealing with a result set
from a stored procedure, you should expect multiple records to
be delimited by the Record or Row mark (Char 255), and fields
to be delimited by Attribute marks (Char 254). The reason for
using a substitute character such as Char(249) for a Record or
what is also known as a segment mark (Char 255) is that most
Pick Host systems can not deal with a segment mark in data
programmatically because this is a reserved delimiter.
|
