/****************************************************************************/
                             CLOCKMAN COMMANDS
/****************************************************************************/
sList = CMEvtItemize (@CMFirst)

Creates a space-delimited list of the ClockMan events.

Parameters:
    (number)    Which events to itemize:
                @CMFirst itemizes all events starting with the first one.
                (This is currently the only value ClockMan recognizes.)

Returns:
    (string)    A space-delimited list of all event IDs in ClockMan's
                database.

After calling CMEvtItemize(), you'd normally loop through the returned list
using ItemExtract() to get each event ID in the string. You use this event ID
to get or set information about the event.

See Also:
    CMGetEvtInfo, CMSetEvtInfo


/****************************************************************************/
sInfo = CMGetEvtInfo (nEventID, nWhichInfo)
nInfo = CMGetEvtInfo (nEventID, nWhichInfo)

Extracts information about an event.

Parameters:
    (number)    Which event to get information on. @CMThisEvt gets info about
                the event that launched this WIL script.
    (number)    Which piece of information to return:
                @CMEvtTime - When this event occurred, in WIL datetime fmt.
                @CMIsActive - Will this event ever occur again?
                @CMMsgType - Returns one of these:
                    @CMMsgAnn - Simple announcement box.
                    @CMMsgCfm - Confirmation box.
                    @CMMsgCount - Countdown box.
                    @CMMsgTSquare - TimeSquare(tm).
                    @CMMsgNone - No message.
                @CMMsg - The message text to display.
                @CMTune - Whether the "Beep" box is checked. @TRUE or @FALSE.
                @CMTuneName
                @CMAction - Returns which action to carry out. One of these:
                    @CMACMsgOnly - Just a message box.
                    @CMACRunPgm - Run a program.
                    @CMACRunWIL - Run a WIL script.
                    @CMACShutdown - Shutdown the computer.
                    @CMACAdj - Adjust the system time up or down.
                @CMPgmLine - The full command line to execute.
                @CMPgmShowAs - How to show the program we launch.
                @CMPgmKeys - The keystrokes to send to the program.
                @CMAdjSecs - How many seconds to adjust the time. (Negative
                number implies adjusting backwards; positive is forwards.)

Returns:
    (string)    if @CMNextTime, @CMMsg, @CMTuneName, @CMPgmLine, or @CMPgmKeys.
    (number)    if @CMIsActive, @CMMsgType, @CMTune, @CMAction, @CMPgmShowAs,
                or @CMAdjSecs.

See Also:
    CMSetEvtInfo

    
/****************************************************************************/
nTime = CMGetSysTime ()

Gets the PC's current system time as a Unix time (secs since 00:00:00 GMT
1/1/70). (For the current time in WIL datetime format, use TimeYmdHms.)

Returns:
    (number)        The number of secs since 00:00:00 GMT 1/1/70.

See Also:
    CMSetSysTime


/****************************************************************************/
sDesc = CMGetTimeDesc (@CMTimeNow, sFmt)

Lets you build a custom date & time string using replacement variables.

Parameters:
    (string)    The time to convert to a string, or @CMTimeNow for the current
                time. (This function currently only recognizes @CMTimeNow.)
    (string)    The format to use in converting the time. You use these 
                replacement variables:
                &dt - Windows-defined short date
                &y4 - 4-digit year
                &yy - 2-digit year
                &MO - Full month name ("January".."December")
                &mo - Abbreviated month ("Jan".."Dec")
                &mm - Month of year w/o leading zeros ("1".."12")
                &0m - Month of year w/leading zero if necessary ("01".."12")
                &DA - Day of week ("Sunday".."Saturday")
                &da - Abbreviated DOW ("Sun".."Sat")
                &dd - Day of month w/o leading zeros ("1".."31")
                &0d - Day of month w/leading zero if necessary ("01".."31")
                &hr - Hour of day ("0".."24")
                &0h - Hour w/leading zero if necessary ("00".."24")
                &mi - Minute ("0".."59")
                &se - Second ("0".."59")

Returns:
    (string)    Your custom date & time string.

This command creates a custom date & time description string using the same
syntax you use to customize the ClockMan icon's title.

Example:
    szNow = CMGetTimeDesc (@CMTimeNow, "It is now &hr:&mi on &DA, &MO &dd")
    sets szNow to "It is now 15:37 on Monday, August 15".
    

/****************************************************************************/
nInfo = CMGetTimeInfo (sTime, nWhichInfo)

Returns information about a specified time.

Parameters:
    (string)    The time to get information about, in WIL "datetime" format
                ("yy:mm:dd:hh:mi:ss").
    (number)    Which piece of information to get from it:
                    @CMYear - The year (00..99)
                    @CMMonth - The month (1..12)
                    @CMDayOfMonth - The day of month (1..31)
                    @CMDayOfWeek - The day of the week (0-Sun..6-Sat)
                    @CMHour - The hours (0..11)
                    @CMMinute - The minutes (0..59)
                    @CMSecond - The seconds (0..59)

Returns:
    (number)    The information requested above.

See Also:
    CMSetTimeInfo


/****************************************************************************/
CMLogMessage (sMessage)

Writes a message out to CLOCKMAN.LOG.

Parameters:
    (string)    The message to write out, up to 256 characters.

This command writes out the current date & time, and then the message you
specify. The log file name is the same as the current .ALR file, except with
a .LOG extension. This is usually CLOCKMAN.LOG.

    
/****************************************************************************/
CMSetEvtInfo (nEventID, nWhich, nData)
CMSetEvtInfo (nEventID, nWhich, sData)


Parameters:
    (number)    Event identifier. (See CMGetEvtInfo)
    (number)    Which piece of data to set. (See CMGetEvtInfo)
    (number) or The new data. It's a string if setting @CMEvtTime, @CMMsg,
    (string)    @CMTuneName, @CMPgmLine, or @CMPgmKeys; it's a number if
                setting @CMMsgType, @CMTune, @CMAction, @CMPgmShowAs, or
                @CMAdjSecs.

@CMIsActive has no meaning within this function. (When you call CMGetEvtInfo
with @CMIsActive, it merely tells you if the event will ever occur again. This
depends on whether it's a recurring or a one-time event, and whether or not
this one time is set in the future or in the past.)

See Also:
    CMGetEvtInfo


/****************************************************************************/
CMSetSysTime (sTime)

Sets the PC's system time.

Parameters:
    (string)        The new system time. This can be the local time in WIL
                    datetime format ("yy:mm:dd:hh:mi:ss") or a single Unix time
                    (secs since 00:00:00 GMT 1/1/70).

See Also:
    CMGetSysTime


/****************************************************************************/
sNewTime = CMSetTimeInfo (sOldTime, nWhichInfo, nData)

Changes specific parts of a WIL "datetime" string.

Parameters:
    (string)    The time to change information about, in WIL "datetime" format
                ("yy:mm:dd:hh:mi:ss").
    (number)    Which info to change:
    (number)    Which piece of information to change:
                    @CMYear - The year (00..99)
                    @CMMonth - The month (1..12)
                    @CMDayOfMonth - The day of month (1..31)
                    @CMHour - The hours (0..11)
                    @CMMinute - The minutes (0..59)
                    @CMSecond - The seconds (0..59)
                    @CMUnixTime - Assumes the string is a single number
                        representing how many seconds have elapsed since
                        00:00:00 GMT on 1/1/70. This will convert it to a
                        WIL "datetime" string.
    (number)    The new data. (Ignored if @CMUnixTime.)

Returns:
    (string)    The time in WIL "datetime" format, with the appropriate data
                changed.

See Also:
    CMGetTimeInfo
