kClient HTML Help: COMMAND FILES

This help consists of:

• General notes
• CMD file's syntax
• Configuration of CMD file feature
• Examples of CMD files

General notes

• In order to make possible to insert data for the KKO system from external sources i.e. external schedule software, there is Scan Folder Feature and searching special CMD files treated as a command file. It makes possible to maintenance your conference via leased conference in the KKO. The kClient software scans given folder (in given path) and if there is a file with "*.cmd" extension, the file is opened, required syntax is analyzed and all line from the file is sent to KKO as a schedule record for executing. Such file is called : CMD - Command File in KKO system.
• Of course, command file have to be in given syntax, it have to consist given parameters etc. In chapter: command file syntax you can find all details about proper syntax of these files. In frame below, you can see example instance where is required: reservation of first conference with entrance password 1234 and release of the conference in given time.
  
  
  
• After detection of CMD command file, such file is decoded, and proper commands are sent to the card automatically. They exist as a schedule records (see: Timetable bookmark) and they are executed according proper rules concern schedule records.
• Via CMD command files it is possible to run following commands:
  • Reservation of the conference in given date and time.
  • Release of reserved conference in given date and time.
  • Password changing for leased conference (in given time).
  • Calling/Removing a subscriber to/from existing conference.
  • Calling/Removing an announcement to/from the conference.
• By changing of parameter's value in command file it is possible to run all commands in following time cases:
  • Only once - the command is executed once, in given date and time.
  • Periodically (e.g. everyday, one per week etc).
  • In given days of week (e.g.: Tuesdays only).
  • Days off or work only.
  • In given period of time only (every few days/hours/minutes).
• In particular, such system makes possible to provide conference according to schedule' timetable like leased conference for external users.
• Only one common directory is required (as a interface base) with common access both kClient software and user's external software.
• After executing all commands from a file (each line is separate command) CMD file can be erased or renamed.
• In kClient software there are many options in order to configure this feature according your requirements and your user profile. All details about this stuff is described in configuration of command files feature in this document.
• A user can switch-on or switch-off this function. By default, CMD feature is inactive.

CMD file's syntax

Syntax of CMD files is described in pdf document: CMD Command Files too. Each row in CMD file is separate command located in one schedule record (see: Schedule). It is possible both : to write one command only in one separate CMD file and to write few commands in separate lines in one CMD file. Each line in such file have to be terminated by CR,LF characters. All commands from one file will be executed one by one chronologically. The order of executing CMD files depends on system settings and you can't be sure that your file sent as first will be executed firstly too. If you want be sure which command will be executed firstly, (control the order) we suggest you include them in one file as a separate lines.

Command file is a text-type file, the name is any, but the extension must be "cmd". More than one such file may be present in scanned directory. In one loop of scanning, (Scanning Folder Interval parameter) the kClient software takes one file only.

In each line of CMD file there are obligatory parameters and optional parameters.

Obligatory parameters have to be in each line and there are as follow:

• "CONF" - number of the conference
• "FREQ" - frequency parameter of execution the record
• "EVENT" - kind of action

Optional parameters are as follow:

• "DATE" - date of execution
• "TIME" - time of execution
• "DIR" - subscriber's phone number
• "ANN" - announcement's number
• "PASS" - access password for the conference
• "GRP" - predefined group number
• "PAR" - additional parameter

All parameters in one line are separated by semicolon or comma character.

CONF

This parameter defines number of conference (1 to 5) for given command.

Proper format is : CONF=n;
where n=1,2,3,4 or 5

FREQ

This parameter defines time/frequency parameter of the command execution.

Proper format : FREQ=n;
where n=1 to 15

Value of this parameter have to be in 1..15 range and each value means following action:

• FREQ=1 - Only once. The record is executed once only in selected day and time. Additional parameters TIME and DATE define time of executing. If these parameters are absent, current date/time will be established.
• FREQ=2 - Once in month. The record will be executed periodically, always in the same day of the month in determined time. Additional parameters TIME and DATE determine time of record execution. As a mater of fact only DAY is required, but full DATE parameter (YYYY-MM-DD) must be written in order to be coherent with the format.
• FREQ=3 - Everyday. This is executed everyday in defined time. Additional parameter: TIME defines time of execution. If TIME parameter is absent, current time (in sending to the card moment) is established.
• FREQ=4 - Every n days. This is executed every n days beginning from current day. Required parameter : PAR=n where n=1..31 days. Additional parameter: TIME defines time of execution the record. If TIME parameter is absent - current time will be established.
• FREQ=5 - Every n hours. This is executed every n hours beginning the TIME. Required parameter : PAR=n where n=1..72 hours. Additional parameter: TIME defines time of execution the record. If TIME parameter is absent - current time will be established.
• FREQ=6 - Every n minutes. This is executed every n minutes beginning the TIME moment. Required parameter : PAR=n where n=5..180 minutes. Additional parameter: TIME defines time of execution the record.
• FREQ=7 - Weekdays. This event will be repeated periodically each "black" day (Monday..Friday) except all days inserted as Additional Days Off (see Timetable->Add.days off).
• FREQ=8 - Weekends. This event will be repeated periodically in Saturday and Sundays (and Additional Days Off - see Timetable->Add.days off) in given time.
• FREQ=9 - In Mondays. This event will be repeated periodically each Monday in time according to TIME parameter. If TIME is absent, current time will be established.
• FREQ=10 - In Tuesdays. This event will be repeated periodically each Tuesday in time according to TIME parameter. If TIME is absent, current time will be established.
• FREQ=11 - In Wednesdays. This event will be repeated periodically each Wednesday in time according to TIME parameter. If TIME is absent, current time will be established.
• FREQ=12 - In Thursdays. This event will be repeated periodically each Thursday in time according to TIME parameter. If TIME is absent, current time will be established.
• FREQ=13 - In Fridays. This event will be repeated periodically each Friday in time according to TIME parameter. If TIME is absent, current time will be established.
• FREQ=14 - In Saturdays. This event will be repeated periodically each Saturday in time according to TIME parameter. If TIME is absent, current time will be established.
• FREQ=15 - In Sundays. This event will be repeated periodically each Sunday in time according to TIME parameter. If TIME is absent, current time will be established.

EVENT

This parameter defines what kind of action have to be executed by schedule record. This parameter have to be present in each line in CMD file.

Proper format : EVENT=n;
where n=1 to 8

Values of this parameter have to be in 1..8 range and the meanings are as follow:

• EVENT=1 - Reservation of the conference. Parameter CONF defines which conference will work. Additionally, the password in leased conference is obligatory parameter (parameter PASS). You want to know, that such conference doesn't release itself (and never doesn't lose the owner automatically). Nobody may be participant of such conference but the owner (Leasing) exists and the access password is valid. So, complementary command "Releasing the conference" (EVENT=7) is always required. This is possible to rewrite old conference by new one. In this case depending on "New conference disconnects old" parameter old conference will be closed or not. It is possible to send only Reservation command (without disconnection) and to work all the time with given conference. In this case the conference is live as long as the KKO card will be electrically resetted. This conference has a owner type "LEASING".
• EVENT=2 - The group calling. This command calls predefined group of participants into earlier reserved conference. Predefined group is stored in memory on the card, so they can be called with one command. Required additional parameter is GRP=n where n=1..32.
• EVENT=3 - The subscriber is calling to conference . This command calls a subscriber as a conference party into earlier reserved conference. Number of subscriber is obligatory parameter (DIR) and this can be string of digits (0..9) with maximum 20 characters length.
• EVENT=4 - The subscriber is removed from the conference. This command released singe party (subscriber) from the conference. Directory number (DIR) is obligatory parameter in this case.
• EVENT=5 - The announcement is connected to the conference. This command calls and inserts prerecorded voice announcement into conference. Number of the announcement is obligatory parameter (parameter ANN=n where n=1..60). The announcement can't be empty. In one time only one announcement can play in the conference. This feature may be useful if the announcement is recorded as a "warning text" (e.g. "Please wait for the connection") before the conference or (e.g. "Note! The conference will be disconnected for 5 minutes!") before the end of the conference. You can use this procedure too if your announcement is main "voice" subject in your conference. In such case it will be broadcasted for all participants of the conference.
• EVENT=6 - The announcement is removed from the conference. This command removes the announcement from selected conference. Number of the announcement is obligatory parameter (ANN). Of course, the same announcement must be earlier inserted into conference (EVENT=5).
• EVENT=7 - Releasing the conference. This is complementary command with "Reservation conference command" (EVENT=1). All participants are disconnected, released and the conferences becomes free (without the owner).
• EVENT=8 - Password changing. This command makes possible to change conference access password in established time without disconnection the conference. Similar effect you can reach by switching off the option "New conference disconnects old one" and command "Conference reservation" command will be done. However it is preferred solution to switch on this option and using this command (EVENT=8) in order to change the password.

DATE

This parameter establish a date in each command.

Proper format is: DATE=YYYY-MM-DD;
where YYYY=year MM-month and DD-day

If this parameter is absent, in each command it means that current date will be established. The format is shown as a patter, the fields separator is '-' character.

TIME

This parameter establish a time in each command.

Proper format is: TIME=HH:MM;
where HH-hour i MM-minute

If this parameter is absent, in each command it means that current date will be established. The format is shown as a patter, the fields separator is ':' character.

DIR

This parameter makes possible to insert directory number (in subscriber's commands).

Ppeoper format is: DIR=nn..n;
where nn..n-subscriber's directory number

In commands with EVENT=3 and EVENT=4 this parameter jest obligatory. Maximum number length is 20 digits, allowed characters are digits '0'..'9'.

ANN

This parameter makes possible to insert announcement's number.

Proper format is: ANN=n;
where n=1 to 60

In commands with EVENT=5 and EVENT=6 this parameter is obligatory. The announcement must be recorded, only one announcement may be in conference in one time. More information about voice announcements in KKO system you can find in chapter voice announcements in the KKO.

PASS

This parameter makes possible to insert conference password.

Proper format is: PASS=nn..n;
where nn..n-password characters

In command with EVENT=1 this parameter is obligatory. Password maximum length is 5 digits, allowed characters are digits '0'..'9'.

GRP

This parameter makes possible to insert predefined group's number.

Proper format is: GRP=n;
where n=1 to 32

In commands with EVENT=2 and EVENT=9 this parameter is obligatory.

PAR

Additional parameter PAR makes possible to insert additional information in command with FREQ=4, FREQ=5 and FREQ=6.

Proper format is: PAR=n;
where n-value of parameter depending on FREQ.

For item "every n days" n must be in 1..31 days range. For item "every n hours" n must be in 1..72 hours range. For item "every n minutes" n must be in 5..180 minutes range.

Configuration of CMD file feature

In kClient software and on the KKO board there are many options in order to make this service more friendly for you. All options from window Schedule->Command Files bookmark are automatically saved in proper configuration file in closing this window moment. If you open this window, all required data from config file are automatically loaded.

There is example configuration window following(Command Files bookmark in Schedule - option):

It this window you can see following options:

• Command files scanning feature state. If this option is checked, your folder isn't scanned, command files aren't explorated and more options are disabled.





• Select disk and directory fields. You have to select destination disk and directory path and approve it bu double clicking or by Enter key. Selected path is your "Scanned folder" for CMD files and only this folder is poled. In proper window field you can check which folder is selected (in our example this is G:\AeRJoT\kClient\command\examples).





• Period of time (frequency) parameter. You are able to change period of time for autoscanning procedure. This time range is 2..60 seconds with resolution 2 seconds. Default value is 10 seconds. In each cycle, one CMD file is taken, next the format and syntax are analyzed and next all data from a file is decoded and sent into KKO card as a schedule records. If the scanning is switched on (option is active, kClient software is working in online state) new small window appears with current remains seconds counter. Too big frequency of scanning (small time period value) value is wrong, because new files usually appears rarely and all PC resources are in action all the time unnecessarily. Too long frequency (big value of time period) causes big delay (about one minute) between sending the file and execution of this file moments.





• Action for executed files. After execution of the file, if the syntax is OK, and the KKO card accept the command, the file can be both: renamed or erased. Following window shows possible settings. If you set erasing option, each executed file disappears from the folder and you can't pay your attention with ungarbagging problem. In renaming case, executed file remains in the directory, you are able to make the history of your file by this way but you have to remove these file yourself. But existing of these files is a document of their execution. In this case you are able to define an extension for such files. Default extension is "old". The window with executed files shows current state of your folder.





• Action for error files. In case of format or syntax error in your command file, the file will be rejected and proper warning window will be displayed on the screen. In such situation, the file is not executed and can be too renamed or erased. Following window shows possible settings. If you set erasing option, each failed file disappears from the folder and you can't pay your attention with ungarbagging problem. In renaming case, rejected files remain in the directory and you are able to make the history of your actions but you have to remove these file yourself. In this case you are able to define an extension for such files. Default extension is "err". The window with failed files shows current state of your folder.





• Data saved in the KKO. Generally speaking the most options for CMD files feature is saved in proper config file. This is automatically opened read, reworked, saved and stored on the disk. But some options according to KKO firmware not kClient software are stored in nonvolatile memory in the KKO card. In order to read, change and store this data you should use buttons: Import and Export. You can set here 2 parameters:
  • Newo conference disconnects old one. If you switch on this option, new conference called with EVENT=1 command, in execution moment will disconnect old conference, all participants will be released and free. Next, new conference will be established with new password. If this option is switched off, new reservation command (with EVENT=1) "rewrite" old conference only. All "old" participants last in new conference, only the password becomes new. Generally speaking, this is preferred settings to switch on this option and change a password with special command (with EVENT=8).
  • Auto erasing executed records. As it mentioned, each line of the CMD file is executed via schedule record. All these records (max 40 pcs) you can see in Schedule option -> bookmark Timetable. If you use records with periodically FREQ parameter, the record remains all the time in the table and always shows date and time of next execution. Status of such record never is "executed" because after previous execution it is recalculated for next action time. However, if you use usually simple records with FREQ=1 parameter (once in the time), such record after execution is useless and it can be removed and its place becomes free for next record. If you switch on this option, executed record will be removed automatically from the list in Timetable. This settings is recommended. In the other case, it is possible to busy all 40 records and next commands will be rejected by full of memory cause.
  Following example shows described options.





• Current passwords. Always in conference reservation command the password for a conference is required (leased conference never exists without a password). You can change a password too by special command (with EVENT=8). So, if "Auto erasing option" for executed records is implemented, it is possible to forget current password (it can disappear from timetable). In order to make possibility of check current password, this option is placed in this window. It concerns leased conference only, inserted via Schedule->Timetable option or via command files feature. Universal passwords (for access into voice menu and for "normal"- not leased conferences) are inserted and edited in Settings window. Here you are able to check only passwords with "leasing" as a owner of the conference. If the conference is busy for "phone" or "dispatcher" or if it is free, you can read text "NONE".





• Owners of conferences. In order to make easy access to information about current owner of each conference, there is possibility of read this information in this window. As it is mentioned in this document, the owner of the conference on the KKO card can be:
  • None - the conference is free, empty, without the owner.
  • Dispatcher - this is user of kClient software, logged on dispatcher level with one or two conferences allocated in login procedure.
  • Phone - this is situation where one conference is reserved by phone with DTMF command '7' or by "Permanent reservation for phone" option in Settings->Conferences.
  • Scheduler - the conference is reserved be schedule record as "Any" conference (not "Leased 1" neither "Leased 2").
  • Leasing - the conference is reserved be schedule record as a "Leased" or by CMD command.
  
  This window can be useful when we want check if the conference is free and after sending the command by CMD file in order to check proper execution our file command.

Examples of CMD files

• Example 1: reservation of the conference "at once".
  
  
  
  
In this case following actions will are executed:
• Reservation of the conference - conference no 1, password 1234.

Pay your attention please, parameters DATE and TIME are absent, so current time and date will be established. So the conference will be reserved in sending this command into a card moment. Such command can be sent into a card in any moment, "wrong time or date" warning never be presented.




• Example 2: releasing and disconnection the conference "at once".
  
  
  
  
In this case following actions will are executed:
• Releasing of the conference - conference no 1.

Pay your attention please, parameters DATE and TIME are absent, so current time and date will be established. So the conference will be ended "at once". Such command can be sent into a card in any moment, "wrong time or date" warning never be presented.




• Example 3: conference in given period of time
  
  
  
  
In this case following actions will are executed:
• Conference reservation - conference no 1, at 12:00 with password 1234.
• Conference releasing - conference no 1, at 14:00.

Pay your attention please, parameter TIME is only present, DATE is empty. So, current date will be established, but the time will be set by TIME parameter value. If such command sent after 12:00, it would be rejected on format/syntax analyzing phase, because it is unexecutable (first command is too old). So, such file would be rejected as a wrong.




• Example 4: conference with full date/time period of time
  
  
  
  
In this case following actions will are executed:
• Conference reservation - conference no 1, on the January 15th 2008 at 12:00 with password 1234.
• Conference releasing - conference no 1, on the January 15th 2008 at 14:30.

Pay your attention please, both time parameters are present, full date/time moment is determined in this command. Such file can't be correctly executed after 15th day of January because "Wrong date" - old date error would be detected.




• Example 5: conference with changeable password
  
  
  
  
In this case following actions will are executed:
• Conference reservation - conference no 2, everyday at 9:00 with password "900".
• Password changing at 10 a.m. - conference no 2, everyday at 10:00 password changing on "1000".
• Password changing at 11 a.m. - conference no 2, everyday at 11:30 password changing on "1130".
• Password changing at 1 p.m. - conference no 2, everyday at 13:00 password changing on "1300".
• Conference releasing - conference no 2, everyday at 15:00.

Pay your attention please, parameter FREQ=3; is used. It means, that that event will be periodically, generated everyday at the same time. If we use such periodic conference we can send it into a card only once (directly in bookmark Timetable) or via CMD command file and the conference will be established everyday. This record doesn't remove itself, because it is periodic-type.

Notice please too it is possible to change a password in a conference many times despite the conference lasts all the time. In our example in each period of time exists various password and with various password's lengths (3 or 4 characters).




• Example 6: complex periodic conference with announcements and leading subscriber-party
  
  
  
  
In this case following actions will are executed:
• Conference reservation - conference no 1 every 8 hours, with password "11111".
• Insertion the announcement - conference no 1, every 8 hours in conference start moment, announcement no 14.
• Removing the announcement - conference no 1, co 8 godzin 5 minut po starcie konferencji, zapowied¼ 14.
• Calling a leader - conference no 1, every 8 hours 5 minutes after conference start, subscriber no 1001.
• Insertion the announcement - conference no 1, every 8 hours 55 minutes after conference start, announcement no 15.
• Conference releasing - conference no 1, every 8 hours, one hour after conference start.

Pay your attention please, the frequency parameter FREQ=5; is used. It means, that the actions will be every given period of time. In our example period of time is 8 (every 8 hours). So, the conference will be active in following periods of time: 6:00-7:00, next 14:00-15:00 and next 22:00-23:00. It is a good solution if the conference services shift-work case where everyday and every shift (always in the same time) the conference is required.

Additionally, notice please that all actions in this conference are as follow:
• Start of the conference.
• Announcement "Please wait for the conference" - during this period all subscribers should calling the conference and enter as a party. They have 5 minutes to entrance before a boss (leader in the conference). This is a stage, where the procedure can be more automatically, simple write all your subscribers into predefined group and call here this group (command with EVENT=2).
• Removing an announcement - calling the boss/conference leader directory 1001. The leader is called after 5 minutes, he is called by KKO card and at entering moment all conference is collected.
• Warning announcement e.g. "Attention, the conference will be disconnected for 5 minutes" - new announcement in "voice background" in the conference (here free 15-th announcement is used in order to create warning about incoming end of conference moment).
• Conference releasing.


If this command sent into the KKO card without TIME parameter, default time would be established. In such situation syntax of this command would be proper, but logically it would be wrong. Time of each command (each line in a file) should be the same, and it should be impossible to insert required offset of the time for each line.

Second notice is following - before execution such command the operator have to record proper announcement. In our example, required announcements shoud be following:
• Announcement no 14: ""Please wait for the conference"
• Announcement no 15: ""Attention! The conference will be disconnected for 5 minutes"