Skip to main content

Controlling InterSystems IRIS from a Windows Client

InterSystems IRIS® data platform provides a mechanism for Windows client programs to control an InterSystems IRIS configuration and to start up InterSystems IRIS processes. This allows you to deliver applications that automatically start InterSystems IRIS processes with the correct configuration information without requiring the standard InterSystems IRIS tools. The tools allow you to:

  • Find InterSystems IRIS directories, paths, and service name for a given configuration name.

  • Get the status of the InterSystems IRIS system.

  • Control an InterSystems IRIS configuration directly or through the InterSystems IRIS Control Service, depending on which version of Windows is running

  • Start an InterSystems IRIS process with the appropriate settings.

You can perform these actions by dynamically loading irisctl.dll and using its functions.

IRISctlGetDirs

Finds configuration, binary, and manager directory paths, and service name for a given configuration name.

Syntax
IRISctlGetDirs(char *config, IRISCTL_DIR_INFO *dirinfo)
config The name of the desired configuration.
dirinfo A pointer to a C structure where the directory information will be stored.
Return Values

Returns (char *0) on ERROR.

IRISctlConfigStatus

Returns the status of the InterSystems IRIS configuration.

Syntax
IRISctlConfigStatus(char* config)
config The name of the desired configuration
Return Values

Returns a value from 0 through 4 as follows:

0 Configuration is up and running.
1 Configuration is starting or stopping.
2 Configuration startup or shutdown aborted.
3 Configuration is down.
4 ERROR

IRISctlControl

Controls an InterSystems IRIS configuration through the InterSystems IRIS Control Service on Windows.

Syntax
IRISctlControl(char *command, char *config)
command Use one of the following commands:

  • start — starts a configuration

  • stop — shuts down a configuration gracefully

  • stopnoshut — shuts down a configuration without running the user-supplied shutdown routine

  • force — forces down a configuration; equivalent to irisforce on UNIX® systems

  • stopstart — shuts down a configuration gracefully and immediately restarts it

config The name of the desired configuration.
Return Values
IRISCTL_SUCCESS Operation succeeded
IRISCTL_ERROR Generic error
IRISCTL_INVALID_COMMAND Invalid command argument
IRISCTL_INVALID_CONFIGURATION Undefined configuration
IRISCTL_CONTROL_STU_ERROR ^STU failed

Following an error return, IRISctlGetLastError returns a pointer to an informational error string.

IRISctlRun

Starts an InterSystems IRIS process in the indicated configuration, and namespace, using the indicated principal I/O device and invoking the indicated routine.

Syntax
IRISctlRun(char *config, char *routine, char *namespace, char *IOtype)
config The name of the running configuration.
routine The name of the desired routine to start.
namespace The name of the desired namespace.
IOtype How I/O is to be handled, with possible values of:

  • terminal — The process starts a new InterSystems IRIS programmer’s terminal.

  • none — No I/O. The process runs in the background with NUL: used for $Principal. Writes to $Principal are discarded. Reads from $Principal produce an error.
Return Values
IRISCTL_SUCCESS Operation succeeded
IRISCTL_ERROR Generic error
IRISCTL_INVALID_COMMAND Invalid command argument
IRISCTL_INVALID_CONFIGURATION Undefined configuration
IRISCTL_CONTROL_STU_ERROR ^STU failed
Note:

On Windows, the specified configuration must be running. If you are not sure if the configuration is running, use IRISctlConfigStatus and IRISctlControl to check and start the desired configuration. This prevents InterSystems IRIS from trying to start a configuration without using the control service.

IRISctlRunIO

Starts an InterSystems IRIS process in the indicated configuration, and namespace, using the indicated principal I/O device type, invoking the indicated routine and additional IO specifications for input, output and error devices.

Syntax
IRISctlRunIO(
        char *config,
        char *routine,
        char *namespace,
        char *IOtype,
        HANDLE *hIO,
        char *cwd,
        char *options,
        HANDLE *child,
        DWORD *childPID))
config The name of the running configuration in all capital letters.
routine The name of the desired routine to start.
namespace The name of the desired namespace.
IOtype How I/O is to be handled, which must have a value of TCP, because the process uses a TCP socket.
hIO An array of three handles to be used as the standard input, output, and error devices of the InterSystems IRIS process.
cwd The working directory path of the child process. If the directory argument is zero, the working directory of the current process is used.
option Additional irisdb.exe command line options appended to the generated command line. For example, you could define a larger process memory size (-b 1024).
child The pointer to a variable of type HANDLE, where the handle to the child process will be returned. If the value of handle is zero, the handle to the child process will be closed by this function.
childPID The pointer to the PID of the created irisdb.exe process. This argument can be zero if the child’s PID is not required.
Return Values
IRISCTL_SUCCESS Operation succeeded
IRISCTL_ERROR Generic error
IRISCTL_INVALID_COMMAND Invalid command argument
IRISCTL_INVALID_CONFIGURATION Undefined configuration
IRISCTL_CONTROL_STU_ERROR ^STU failed
Note:

The handles in the hIOarray must be inheritable. Use DuplicateHandle to make the handle inheritable by the child process.

On Windows, the specified configuration must be running. If you are not sure if the configuration is running, use IRISctlConfigStatus and IRISctlControl to check and start the desired configuration. This prevents InterSystems IRIS from trying to start a configuration without using the control service.

Using ^GBLOCKCOPY for Fast Global CopiesNext section
Previous sectionExtending Languages with ^%ZLANG Routines
FeedbackOpens in a new tab