Zcommand is an Interactive Processing Object. It enables access to a ZIM database and has all the capabilities of a Zim multi-user database agent. It can present two different (mutually-exclusive) command interfaces: an operating system command line interface and a ZIM 1202 interface. Zcommand also has the ability to communicate with other ZIM 1202 compatible objects.
The command line version of the Zim multi-user DB agent (zcommand) has a connector mode of operation that is indicated by using the ’-c’ command line argument. This causes the zcommand instance to listen on the specified port and receive requests over a socket connection. This allows any ZIM 1202 compatible process access to the database that the zcommand has access to. Like the command line version of zcommand the connector instance relies on environment variables to indicate the working directory, database and Zim install directory location. When started as a connector, Zcommand expects to find a text file called conconf.txt in the database directory; this file contains the password required to maintain a connection to this instance of zcommand.
Unlike the existing ZimDBAgent, the client does not have to have any pre-existing knowledge of the nature of the data stored in the database. It is possible for the client to get the metadata definitions for the database objects and thereby dynamically construct a model of the data store.
set ZIM="C:\\Program Files\\Zim\\7.1"
set ZIMDBDIR="D:\\MyDBZim"
set ZIMWORKDIR=" D:/MyDBZim /workdir"
zcommand –c <listen port>
The environment variable ZIM is the ZIM installation directory path. ZIMDBDIR is the path to the database to be accessed and ZIMWORKDIR is the path to the working directory for this connection. Each zcommand instance requires its own working directory; if you need multiple zcommand instances on the same database it is better to use zmultiplex. The Zcommand connector will auto-sense between ZIM 1202 and rootDataObject XML format and respond in kind. Only the ZIM 1202 interaction in explained in this section; the mapping to rootDataObject XML should be evident by examining the XLM schema definition for described previously.
General Message Construction (To Connector)
|
ZIM 1202 Field |
Contents |
Notes |
|
SegmentRN |
A word or number |
Groups together a collection of segment groups. This should be the same for all segments in the message. |
|
GroupID |
The command group indicator |
This will group a set or segments into a command set. |
|
SegmentID |
A Number |
Each segment should have a different ID number within the group, zero indexed, ascending |
|
SegmentType |
Literally CONNECT or COMMAND |
The case sensitive word COMMAND or CONNECT. |
|
DataName
|
One of COMMAND or PASSWORD |
Use COMMAND for SegmentType COMMAND and use PASSWORD for SegmentType CONNECT. |
|
DataType |
A word or number |
This will be the SegmentRN for all responses generated by the command. |
|
DataValue |
The command arguments |
These are the command specific arguments. |
Command: CONNECT
Interface: Command Socket
Arguments: The connector password in the DataValue field.
Action: If the CONNECT command is absent from a message or the password in the DataValue field does not match the connector password, then the connection is dropped with no feedback.
Command: COMMAND
Interface: Command Socket
Arguments: The command or part command in the DataValue field.
Action: Execute the command
Command Execution
A single ZIM 1202 message sent to the zcommand connector may contain zero or more groups of commands and each of these commands may contain many lines. Zcommand processes a message in the following way:
Verify the PASSWORD
For each different GroupID
Process the DataValue fields as if they had been types into a terminal session, including recognizing the line concatenation character ’\’
Send a message back for each command output set in the Group using the contents of the DataType as the response SegmentRN.
Send a PROMPT message
Each time a prompt would normally be generated by a Zim terminal session (between commands) the zcommand connector will return a message. If the message generated output (a ’list’ command) then the output data is sent in the message. If the command would normally write to the terminal (an output command) then a message containing the output is returned. If the command generated an error then the error is returned. Finally after all commands have been attempted a PROMPT message is returned.
The message that is sent to a subscriber will have the following:
|
ZIM 1202 Field |
Contents |
Notes |
|
SegmentRN |
The DataType field from the COMMAND segment |
Groups together a collection of segment groups. This should be the same for all segments in the message. |
|
GroupID |
The Numeric GroupID |
Each group of related segments (a DB row) will have the same GroupID number |
|
SegmentID |
1 - n
|
Each segment will have a different ID number, one indexed, ascending |
|
SegmentType |
One of DATA, STDOUT, STDERR or PROMPT |
Literally the word DATA, STDOUT, STDERR or PROMPT |
|
DataName
|
Either OUTPUT or a backing store data specification |
If the SegmentType is STDOUT, STDERR or PROMPT this filed will contain the literal OUTPUT. see below for the construction of a backing store data specification |
|
DataType |
Either CHAR or NULL |
Literally the word CHAR or the work NULL |
|
DataValue |
The first 1024 bytes of the value of the attribute. |
The value of the data, Note if the DataType is NULL then the backing store returned NULL for this value. |
Format:
<field name>:<field type>:<length>:<decimals>:<special>
Where
Field name is the name (not the display name) of the field.
Field Type is the data type of the field (ALPHA, VASTINT, VARCHAR, etc).
Length is the length of the field in the database.
Decimals is the number of decimal places in the data.
Special is: READONLY for read–only data, NULLS if the field allows NULL values, NONULLS if the field does not allow NULL values and SEQUENCE if the field is an automatically generated sequence number.
Examples:
Phone:ALPHA:18:0:NULLS = A thirty byte APLHA field called Phone that may have a NULL value.
Temp:NUMERIC:6:2:NONULLS = A six byte NUMERIC field with 2 decimal places (xxxx.xx) called Temp that may not contain a NULL value.
The `Terminal Session` illustrated in the previous section Protocol->Sample Single Query Interaction was done using a connection to zcommand running as a connector. The client Zim instance defined the following document:
Document Name FileName
FinanceDatabase_PS S!amccue!5006
A zcommand was started on the system amccue with the following commands:
set ZIM="C:\\Program Files\\Zim\\7.1"
set ZIMDBDIR="D:\\MyDBZim"
set ZIMWORKDIR=" D:/MyDBZim /workdir"
zcommand –c 5006