OpenTP1 Version 7 Programming Reference C Language
dc_adm_call_command - Execute an operation command
Format
ANSI C, C++
#include <dcadm.h> int dc_adm_call_command (char *com, int *stat, char *outmsg, DCULONG *outsiz, char *errmsg, DCULONG *errsiz, DCLONG flags) |
K&R C
#include <dcadm.h> int dc_adm_call_command (com, stat, outmsg, outsiz, errmsg,errsiz, flags) char *com; int *stat; char *outmsg; DCULONG *outsiz; char *errmsg; DCULONG *errsiz; DCLONG flags; |
Description
The function dc_adm_call_command() passes com from the UAP to sh(1) as in the case of command entry in online mode. The process waits until the shell completes its processing, and returns the exit status of the shell. After command processing is completed, the standard output information and the standard error output information are returned.
If the OpenTP1 uses UAPs which execute operation commands, add the directory containing the commands to the search path. Use any of the following methods for addition to the search path.
Arguments whose values are set in the UAP
com
Specify the character string of the operation command to be executed.
outsiz
The execution results of the operation command are output to the standard output file. Specify the size of the contents (value returned to outmsg) in bytes. Pre-allocate the area in size of the number of bytes that is to be specified for outsiz. The area must begin from the address pointed to by outmsg. The number of bytes to be specified for this argument must be decided according to the command executed by the UAP.
After processing terminates, the actual length that was output as the execution results of the command to the standard output file is returned.
errsiz
The execution results of the command are output to the standard error output file. Specify the size of the contents (value returned to errmsg) in bytes. Pre-allocate the area in size of the number of bytes that is to be specified for errsiz. The area must begin from the address pointed to by errmsg. The number of bytes to be specified for this argument must be decided according to the command executed by the UAP.
After processing terminates, the actual length that was output as the execution results of the command to the standard error output file is returned.
flags
Specify the operation of the function dc_adm_call_command() if the complete data of a standard output message or standard error output message cannot be acquired.
Arguments whose values are returned from OpenTP1
stat
A shell termination code# is returned indicating whether the specified command terminated normally or abnormally.
outmsg
The character string that was output as the execution results of the command to the standard output file is returned. The maximum number of bytes for the character string is (outsiz-1). If the character string exceeds the maximum number of bytes (outsiz-1), the excess characters are truncated. If the character string exceeds the capacity of the pipe, the excess characters are also truncated. If the character string does not reach the maximum number of bytes (outsiz-1), the entire character string is returned. A null character is suffixed to the character string to be stored.
outsiz
The length of the character string that was output as the execution results of the command to the standard output file is returned.
errmsg
The character string that was output as the execution results of the command to the standard error output file is returned. The maximum number of bytes for the character string is (errsiz-1). If the character string exceeds the maximum number of bytes (errsiz-1), the excess characters are truncated. If the character string exceeds the capacity of the pipe, the excess characters are also truncated. If the character string does not reach the maximum number of bytes (errsiz-1), the entire character string is returned. A null character is suffixed to the character string to be stored.
errsiz
The length of the character string that was output as the execution results of the command to the standard error output file is returned.
Return values
Return value | Return value (numeric) | Explanation |
---|---|---|
DC_OK | 0 | The shell termination code is 0 (normal termination of the command execution). The character string was stored in the standard output area and the standard error output area. |
DCADMER_STATNOTZERO | -1855 | The shell termination code is not 0 (abnormal termination of the command execution). Standard output data and standard error output data were stored in the areas. |
DCADMER_PARAM | -1852 | The argument value is invalid. |
DCADMER_MEMORY_OUT | -1856 | All the standard output data could not be stored in the area. |
DCADMER_MEMORY_ERR | -1857 | All the standard error output data could not be stored in the area. |
DCADMER_MEMORY_OUTERR | -1858 | Both the standard output data and the standard error output data could not be stored in the areas. |
DCADMER_SYSTEMCALL | -1859 | A system call (close, pipe, dup, or read) could not be executed. |
Note
Be careful not to duplicate the command name between directories that are specified as search paths. The correct command will not execute if the command name is duplicated. In addition, be careful not to duplicate the command name with that of the command group provided by OpenTP1 (under $DCDIR/bin).
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.