pmctl

Preprocessed Parameters

Parameters may be preprocessed using parentheses. Preprocessed parameters expand the range of input pmctl can use when building a request. They allow for parameters to be read from files, remote resources, and for pass phrases to be securely requested from the command line.

Some complex parameters must be preprocessed. These parameters include those that require structures or arrays.

bash$ ./pmctl scheduler.set event=(plist:file:///Users/Shared/event.plist)

Permitted formats include:

• json
• plist
• raw
• text

bash$ ./pmctl eventstore.store events=(plist:https://example.com/events.plist)

name=(json:URL)
name=(plain:URL)

bash$ ./pmctl scheduler.set event=(plist:file:///Users/Shared/event.plist)
bash$ ./pmctl scheduler.set event=(plist:http://www.example.com/event.plist)
bash$ ./pmctl scheduler.set event=(plist:https://www.example.com/event.plist)

-p 'name=(raw:contents)'

bash$ ./pmctl -r scheduler.remove -p 'unique ID=(raw:(plist:file:///tmp/))'

Multiple Requests

Multiple requests can be sent by appending the requests to the command. A single connection is created and the requests are issued in the order provided on the command line.

pmctl sends one request at a time. pmctl may interrupt the requests, if authentication is required by the Scheduler. In this case, the authentication must be completed successfully before the remaining requests are sent.

Responses to multiple requests are grouped and output as a dictionary or an associative array:

bash$ ./pmctl build.version notifications.warningperiod notifications.notifyperiod
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>build.version</key>
        <string>uk.co.dssw.powermanager.pmd v5.0.0</string>
        <key>notifications.notifyperiod</key>
        <integer>900</integer>
        <key>notifications.warningperiod</key>
        <integer>3</integer>
    </dict>
</plist>

Character Encoding

All character encoding and input is assumed to be UTF8. Providing input in other encodings may can authentication to fail.

UTF8 encoding is the default for macOS's Terminal.app application.

Parameter Coercion

Parameters need to passed to Power Manager in specific formats. All parameters provided directly from command line arguments are strings; in many cases strings are not the appropriate format.

Type coercion is limited in the possible conversions that can be performed. Where a conversion is not possible, the original parameter is left untouched. In this situation the request is expected to fail with an error message explaining which parameter is invalid.

pmctl can coerce parameters manually by extending the request format.

bash$ ./pmctl scheduler.setenabled enabled:boolean=true

To coerce a parameter, insert a final parameter type into the request before the equals symbol. Supported types include:

• boolean
• date
• integer
• real
• string