Element

Description

Number

0

Constant

vxOpenConnectionCmd

Input Arguments

1 = Script - Connection Script from MSD object.

Output Arguments

1 = Handle - Base Connection Handle.

Operation

This message is handled by the Vpmv20.dll library functions and the Server protocol. It is used to start-up communications, establishing an initial connection between the client and the server. Each subsequent client message will include the connection handle returned by the server as the result of a connection being made.  For the rest of the messages, it is assumed that any message sent by the client is prefaced with the connection handle.

Element

Description

Number

1

Constant

vxLoginServerCmd

Input Arguments

1 = User - User ID Name.

2 = Password - Optional password for account access.

Output Arguments

1 = Server Handle - The  Server Connection number for this session.

Operation

The server program reads the CONNECTIONS record from the VSCONTROL file (in the server account). Tries to locate the user in the existing connections. If the User Name is not found, the server will see if any connections are available (i.e. it will verify the total number of licensed connections is not exceeded).

If there is a connection available, the program retrieves the User Record from the VSUSERS file. If the user is not defined, the process returns an error. The password sent by the client is checked against the password on the User record. If the passwords are not the same, an error is returned.

Element

Description

Number

2

Constant

vxOpenDatabaseCmd

Input Arguments

1 = Server Handle - Server Number.

2 = Account Name - Pick Account Name (Database Name) to Open (set pointer to).

Output Arguments

1 = Database Handle - The Number assigned to this database for this session.

Operation

The server program first verifies that the Server Handle passed matches the current server process. It gets the Account Name from VSDATABASE file (mapping file). If the account is found, the process checks to make sure the connection/user has the correct permission codes. The permission codes needed to open a database are: D - Read Definitions and R - Read Data.

Element

Description

Number

49

Constant

vxCloseDatabaseCmd

Input Arguments

2 = Database Handle - The Number assigned to this database for this session.

Output Arguments

None

Operation

The server program firsts verifies the database number passed is an active database number. It then goes through and UN-Locks all locked files (on the host, if any). It also cleans up and/or clears all associated internal (server) variables associated with that database.  It then releases the assigned database number.

Element

Description

Number

98

Constant

vxLogOffServerCmd

Input Arguments

1 = Server Handle - The number assigned for this server session.

Output Arguments

None

Operation

The program verifies the server number passed is the correct and active server number. The program then goes through each currently active database and UN-Locks the files that may be locked. The connection is then deleted from CONNECTIONS record in the VSCONTROL file. This then allows another connection.

Element

Description

Number

99

Constant

vxCloseConnectionCmd

Input Arguments

1 = Handle - Base Connection Handle.

Output Arguments

None

Operation

This message is handled by the Vpmv20.dll library functions and the Server protocol. It closes the base connection to the server, shutting down the serial or network communication protocol in use. It then releases the base connection handle for use by other connections.

Element

Description

Number

3

Constant

VxOpenQueryCmd

Input Arguments

1 = Server Handle - The number assigned for this server session.  

2 = Query Type – 0 for a Record Query, non-zero for an Action Query.

3 = Database Handle - The number assigned to the database (Pick account) during the open database function.

4 = Table List - A multi-valued list of actual table (file) names.

5 = Table Flags - A multi-valued list of table (file) operations: 1 for Selecting Records; 2 for Updating Records; 4 for Adding New Records; 8 for Deleting Records; 16 for Locking Records; 32 for Locking records at read  time; 128 for Re-reading records before update lock. Note: the table flags usually would come as one number by just adding up the data (e.g. a flag of 47 could only be obtained by passing a 1, 2, 4, 8, 32).

6 = Field List - A sub-valued list of actual field names correlated with the multi-valued list of actual table names in the Table List.

7 = Select Fields - A multi-valued list of selection field references and criteria:  Table number; Field number; operator number (0 for =; 1 for not equal, …); logical number (0 for none, 1 for or, 2 for and); not number (0 for off, 1 for on); lp (left parenthesis) number; rp (right parenthesis) number.

8 = Join Fields - A multi-valued list of join field references: Table number: Field number; Table number: Field number; Join Type; Join Operator. Join Types: 1 (inner), 2 (left outer), 3 (right outer). Join Operator: 0(=), 1(<>), 2(<), 3(>), 4(<=), 5(>=).

9 = Order by Fields - A multi-valued of sort field references and sort order: Table Number: Field Number: Order (0 ascending, 1 descending).

10 = Extract Fields - A multi-valued list of read/extract field references: Table Number: Field Number.

11 = Update Fields - A multi-valued list of write/update field references: Table Number: Field Number.

12 = Insert Fields - A multi-valued list of write/insert field references: Table Number: Field Number.

Output Arguments

1 = Query Handle - The number assigned to the defined query.

Operation

The server program first goes through and retrieves the first available query number (a maximum of 50 queries are allowed). It then verifies that the database number sent is accurate.  The program goes through each of the tables (files) defined and will do the following:

1) Check to see if the table (file) has been mapped: Verify the table is defined in the VSDATABASE file (key is Database Name \ Table Name).

2) Validate the permissions: Must return at a minimum the permissions of  D Read Definitions and R Read Data.

3) Open the dictionary and the data portion (remotely from the MVSERVER account) file: Find the next available file number (a maximum of 100 files are allowed).

4) Check to see if this file has been defined as Virtual Table in the mapping process. A Virtual Table may be a sub-valued or a multi-valued definition.

5) Go through the associated fields for this table and do the following:

1. Determine the next available field number (a maximum of 300 fields are allowed).

2. Validate whether the field has already been mapped: Verify the field is defined in the VSDATABASE file (key is Database Name \ Table Name \ Field Name).

3. Validate the permission for this field is at least an R Read Data.

4. mapped field definitions.

The server program then checks to see if any Select Fields were passed by the client.  If there were select fields passed, the program does the following:

1) Builds up an internal variable called FL.SELECT. This variable is a dimensioned array based (the dimension part) on the file number.  It will be updated with the following multi-valued information:

1. The internal field number (this will reference which internal FDEFS this select field is associated with)

2. The field number passed from the client.

3. The operator number passed by the client.

4. The logical number passed by the client.

5. The not number passed by the client.

6. The lp number passed by the client.

7. The rp number passed by the client.

8. The query number defined for this query.

9. The selection number passed by the client (i.e. the first, or second, or third, etc. select passed for this query by the client).

10. The type of virtual table associated with this selection. The type may be multi valued or sub valued.

2) Builds up the appropriate internal variables if this select has any Join data.

3) The program determines what kind of query has been passed by the client. If the query is a standard Entry Screen defined by Vantage Application Factory, the program will setup the appropriate internal variables to read/ extract/ update / insert data into the defined files. If the query is a user-defined query, the program may additionally build up a select statement (i.e. Select File with by").  

The server program will then setup all the internal variables required to EXTRACT, UPDATE, and INSERT the data passed by the client.

Element

Description

Number

48

Constant

vxCloseQueryCmd

Input Arguments

2 = Query Handle - The number assigned in the Open Query Process. 

Output Arguments

None

Operation

The server program verifies the query number as a valid and active query. The process unlocks any and all files locked by the query, then cleans up and initializes the internal query variables.

Element

Description

Number

31

Constant

vxBeginTransCmd

Input Arguments

1=Server Handle - The number assigned for this server session.

Output Arguments

1 = Return code - A one (1) if successful, zero (0) if it failed.

Operation

The server program verifies the server number passed is the correct and the active server number. The server will then increment the internal variable TRANSACTION by 1.

Note: during any Update/Insert process, if the variable TRANSACTION is set to any number larger than zero, the file VSSTAGE will be updated (therefore not the real destination file).

Element

Description

Number

32

Constant

vxCommitCmd

Input Arguments

1 = Server Handle - The number assigned for this server session.

Output Arguments

1 = Return code - A value of 1 if the Commit was successful, zero if a failure occurs.

Operation

The server program verifies the server number passed is the correct and active server number. It will then verify that there are transactions outstanding by checking to see if the variable TRANSACTION has a number larger than zero (0) in it.

The server will go through the VSSTAGE file, selecting the records for this connection, and for this transaction, update the appropriate files/records/fields.

The VSSTAGE file is setup as follows:

Key

Each item in the VSSTAGE file has its item id as any Pick item has. Because the stage file is shared with all users (connections), the key must have the connection number as one of its parts. The stage file may also represent multiple begin transaction levels. Therefore, the key also must have which level of transaction it represents and have the file and record id for that file. The following is an example of a key:

1\2\3\COMPANY

Where:

1        Connection number. This is the first connection.

2        Transaction number. This is the second transaction. In this case, there were two Begin transactions (31) sent by the client.

3        Record Id. This is the record id of the file. In this example, the file name is COMPANY.  This file will be updated.

Item 

The stage item is divided into two parts: The first part is a multi-valued list of the actual attribute numbers to update. The location of each attribute number in the list is important. The location corresponds to where, within the item, the associated data exist.  For example: the first multi-values data will be attribute 2; the second multi-values data will be in attribute 3; and so on.

The second part is where the data is stored. Attributes 2 and up contain the data which will replace the current data (if any) on the file. The following is an example of an item:

001 1 ] 5 ] 10

002 XYZ Company, Inc.

003 Albuquerque

004 10 ] 20 ] 30 ] 40

Where:

Attribute one (1) contains three (3) multi-values.  Using the key defined above, the COMPANY file with the record key of 3 will be updated; attribute 1 will be replaced with the contents of attribute 2 (XYZ Company, Inc.); attribute 5 will be replaced with Albuquerque (contents of attribute 3); and attribute 10 (of the COMPANY file) will be replaced with the multi-valued data of 10]20]30]40.

Element

Description

Number

33

Constant

vxRollbackCmd

Input Arguments

1 = Server Handle - The number assigned for this server session.

Output Arguments

1 = Return code - A value of 1 will be passed if Rollback was successful, zero if a failure occurs.

Operation

The server program verifies the server number passed is the correct and active server number. It will verify that there are transactions outstanding by checking to see if the variable TRANSACTION has a number larger than zero (0) in it.

The server will select the VSSTAGE file with the connection number passed by the client and for the current transaction level (as defined by internal variable TRANSACTION). It will then delete, or remove, the records from the VSSTAGE file and unlock any locks set.  The TRANSACTION variable will be reduced by 1.

Element

Description

Number

11

Constant

vxSelectCmd

Input Arguments

2 = Query Handle - The number assigned in the Open Query Process.

3 = Select Values - A multi-valued list of values matching the Select Fields (Where clauses) of a Query.

Output Arguments

1 = Return code - 0, No records selected; 1, One record returned; -1, Multiple records returned (cursor will be positioned at the first record).

Operation

The server program will verify the query number passed is a valid and the active query. If the file used in the query is not a virtual table, the server program will go through and unlock any previously locked records associated with the current query.

The server will then attempt to select the first record of the query. The record will be retrieved based on how the query was originally. The server may do a simple read or it may select a table (file), reading the first record from the list.  In the case of a virtual table (an correlated list of multi-valued or sub-valued fields), the data is retrieved from the base file.

If no records were found (selected), a 0 will be returned back to the client. If there was a record found, the server will try to retrieve a second record. If it was possible to retrieve another record, the server will return a -1 to the client (reporting multiple records were found). If an additional record was not found, the server will return a 1, indicating a single record was selected.

Element

Description

Number

12

Constant

vxUpdateCmd

Input Arguments

2 = Query Handle - The number assigned in the Open Query Process.

3 = Update Records - The actual record(s) to be updated. If more than one record is to be updated, the delimiter between each record will be an attribute mark. A multi value mark will delineate each field within the record.

Output Arguments

1 = Return code - 0 - No successful updates. n - Number of records updated.

Operation

The server program will first verify the query number passed is a valid and active query.

The server will take the update record(s) passed by the client, go through each field and perform any conversion needed to update data into a Pick field (for example, will take a date in external format and convert it to an internal date). The server will then update all appropriate internal data variables with the converted data.

If the variable TRANSACTION has a number greater than zero (0), meaning, there was a Begin transaction sent by the client, the program will update the VSSTAGE file with the data to be updated (for a more complete discussion of the VSSTAGE file, see the Commit (32) message reference). That data will reside in the VSSTAGE file until a Commit or Rollback has been sent by the client. If there are any virtual tables (files) associated with the table (file) being updated the data in those tables will also be updated to the VSSTAGE file.

If there was no Begin transaction sent by the client, the program will by-pass updating the VSSTAGE file, writing directly to the appropriate file(s).

If a virtual table is being sent for updated and that table is associated with a base table, the program will only store the data into the internal variables until such time as the base file is updated. If the virtual table does not have an associated base table, the program will update the virtual table as if it were a normal file.

Note: The Update Records parameter must have Attribute marks Char(254) delimiting records, and Value marks Char(253) delimiting fields. When working at the client side with dynamic array records that are sent or received from mvServer, you must use the Record or Row mark (Char 255) to separate records and the Attribute mark (Char 254) to separate fields. The HostSendMessage routine of the channel database object, which handles all communication with the Vpmv20.dll file, converts the delimiters before passing them to and from the Vpmv20 DLL functions. An Attribute mark (Char 254) is converted to the needed Value mark (Char 253), and the Record Mark Char(255) is converted to the Attribute mark Char (254), when sending data to Vpmv20 DLL routines. The conversion is in the reverse for dynamic array records received from Vpmv20 DLL routines.

Element

Description

Number

13

Constant

vxDeleteCmd

Input Arguments

2 = Query Handle - The number assigned in the Open Query Process.

3 = Record Count - The number of records to be deleted from the current record pointer.

Output Arguments

1 = Return code - 0 - No successful updates. n - Number of records deleted.

Operation

The server program will first verify the query number passed is a valid and active query

If the variable TRANSACTION has a number greater than zero (0), meaning, a Begin transaction was sent by the client, the program will update the VSSTAGE file with a record signifying that the current data is to be deleted. That record will reside in the VSSTAGE file until a commit or rollback has been sent by the client. Once a Commit is sent, the program will delete the information from the appropriate files.

If there was no begin transaction sent, the program will carry out the delete immediately.

Element

Description

Number

14

Constant

vxInsertCmd

Input Arguments

2 = Query Handle - The number assigned in the Open Query Process.

3 = Insert Records - The actual record(s) to be inserted. If more than one record is to be inserted, the delimiter between each record will be an attribute mark. A multi-value mark will delineate each field within the record.

Output Arguments

1 = Return code - 0 - No successful updates. n - Number of records inserted.

Operation

The server program will first verify the query number passed is a valid and active query.

The server will take the inserted record(s) passed by the client, go through each field and perform any conversion needed to update data into a Pick field (for example, will take a date in external format and convert it to an internal date). The server will then update all appropriate internal data variables with the converted data.

If the variable TRANSACTION has a number greater than zero(0), meaning, there was a Begin transaction sent by the client, the program will update the VSSTAGE file with data to be inserted (for a more complete discussion of the VSSTAGE file see the Commit (32) message reference). That data will reside in the VSSTAGE file until a Commit or Rollback has been sent by the client. If there are any virtual tables (files) associated with the table (file) being inserted, the data in those tables will also be updated to the VSSTAGE file.

If there was no Begin transaction sent by the client, the program will by-pass updating the VSSTAGE file, writing directly to the appropriate file(s).

If a virtual table is being sent to be inserted and that table is associated with a base table, the program will only store the data into the internal variables until such time as the base file is updated.  If the virtual table does not have an associated base table, the program will update the virtual table as if it were a normal file.

Note: The Insert Records parameter must have Attribute marks Char(254) delimiting records, and Value marks Char(253) delimiting fields. When working at the client side with dynamic array records that are sent or received from the mvServer, you must use the Record or Row mark (Char 255) to separate records and the Attribute mark (Char 254) to separate fields. The HostSendMessage method of the channel database object, which handles all communication with the Vpmv20.dll file, converts the delimiters before passing them to and from the Vpmv20 DLL functions. An Attribute mark (Char 254) is converted to the needed Value mark (Char 253), and the Record Mark Char(255) is converted to the Attribute mark Char (254), when sending data to Vpmv20 DLL routines. The conversion is in the reverse for dynamic array records received from Vpmv20 DLL routines.

Element

Description

Number

21

Constant

vxSetPosCmd

Input Arguments

2 = Query Handle - The number assigned in the Open Query Process.

3 = Reference - Starting position reference. 1 = first record; -1 = last record ; 0 = current record.

4 = Offset - Number of record positions to move record pointer from starting position.

Output Arguments

1 = Return code - 0 = New position is not valid. n = Cursors current position.

Operation

The server program will first verify the query number passed is a valid and active query. This message is to position the record cursor within the result set of the given query.

If the client passed a reference of 1, the server will set the record position to the first record number, plus the offset value. If the client passed a reference of 0, the server will set the record position to the current position plus the offset value. If the client passed a -1, the server will set the current record position to the last record, plus the offset value.

Element

Description

Number

22

Constant

vxFetchCmd

Input Arguments

2 = Query Handle - The number assigned in the Open Query Process.

3 = Record Count = The number of records to be retrieved from the current cursor position.

Output Arguments

1 = Return code - Number of records fetched.  A zero means no records were fetched. If records were fetched, the number of those records will be returned.

2 = Fetched Results - The record(s) fetched with be delimited by an attribute mark (if more than one record was sent to the client) for each record. Each field will be delineated by a multi-value mark.

Operation

The server program will first verify the query number passed is a valid and active query.

The program will then retrieve all the extracting information from query definitions. For each field to be fetched, the program will go through and perform any conversions (i.e. date, currency, numbers, etc.) needed prior to sending data to the client. The server then combines the record with any other records needing to be sent, and sends the information to the client.