interface for writing ELOG entries with Igor graphs as attachment. More...

Namespaces
	PearlElog
	interface for writing ELOG entries with Igor graphs as attachment.

Functions
variable	pearl_elog (string logbook)
	main function to initialize ELOG and to open an ELOG panel. More...

static variable	IgorBeforeNewHook (string igorApplicationNameStr)
	save preferences and recent values before Igor opens a new experiment. More...

static variable	IgorQuitHook (string igorApplicationNameStr)
	save preferences and recent values before Igor quits. More...

static variable	AfterFileOpenHook (variable refNum, string file, string pathName, string type, string creator, variable kind)
	initialize the package and reload preferences after an experiment is loaded. More...

static dfr	get_elog_df (string name, variable category)
	get the package, logbook, or template datafolder. More...

static variable	init_package (variable clean=defaultValue)
	initialize the package data folder. More...

variable	elog_init_pearl_templates ()
	setup PEARL template logbooks. More...

static variable	init_volatile_vars ()
	initialize volatile variables. More...

variable	elog_create_logbook (string name, string template=defaultValue)
	create a new logbook. More...

variable	elog_config (string elog_path=defaultValue, string hostname=defaultValue, variable port=defaultValue, string subdir=defaultValue)
	set global module configuration parameters More...

variable	elog_login (string logbook, string username, string password)
	set username and password for login to a logbook More...

variable	elog_logout (string logbook)
	clear username and password of a logbook or all logbooks. More...

static variable	save_prefs ()
	save persistent package data to the preferences file. More...

static variable	load_prefs ()
	load persistent package data from the preferences file. More...

static string	list_logbooks (variable templates=defaultValue)
	get a list of configured logbooks or templates. More...

variable	elog_validate_attributes (string logbook, string attributes)
	validate attributes More...

variable	elog_create_entry (string logbook, string attributes, string message, variable encoding=defaultValue, string graphs=defaultValue, variable replyto=defaultValue)
	create a new entry in ELOG More...

variable	elog_add_attachment (string logbook, variable id, string graphs)
	add one or more graphs to an existing ELOG entry More...

static string	prepare_command_line (string logbook)
	format the ELOG command and essential address arguments. More...

static string	format_url (string logbook)
	format the URL for display to the user More...

static string	prepare_graph_attachments (string graphs)
	prepare screenshots of graph windows for attachments More...

static string	get_timestamp (string sep)

static string	create_message_file (string message)
	save the message to a temporary text file More...

static string	create_graph_file (string graphname, variable fileindex)
	save a graph to a temporary graphics file More...

static string	create_cmd_file (string cmd)
	write the command line to a file. More...

static string	get_log_path ()

static variable	cleanup_temp_files ()
	delete temporary files created by the ELOG module. More...

static variable	parse_result ()
	parse the result file from an elog invokation. More...

string	elog_prompt_logbook ()
	prompt to open or create a logbook More...

variable	elog_prompt_login (string logbook)
	prompt the user for login to a logbook More...

string	PearlElogPanel (string logbook)
	open a new panel for submitting data to ELOG. More...

static variable	elog_panel_hook (WMWinHookStruct *s)

static variable	update_attach_items (string logbook)
	update the list of attachments More...

static variable	move_attach_item (string logbook, variable item, variable distance)
	move an attachment item in the list of attachments More...

static variable	bp_attach_updown (WMButtonAction *ba)
	button procedure for the attachment up and down buttons More...

static variable	bp_submit (WMButtonAction *ba)
	button procedure for the Submit and Reply buttons More...

static variable	bp_attach_top (WMButtonAction *ba)
	select top graph window for attachment More...

static variable	bp_attach_allnone (WMButtonAction *ba)
	select/deselect all graph windows for attachment More...

static variable	bp_attach (WMButtonAction *ba)

static variable	bp_save_graphs (WMButtonAction *ba)

static variable	bp_clear (WMButtonAction *ba)

static variable	bp_login (WMButtonAction *ba)

static variable	bp_logout (WMButtonAction *ba)

static string	get_default_panel_name ()

static string	get_panel_attributes (string windowname)
	get a list of attributes from the fields of the ELOG panel. More...

static string	set_panel_attributes (string windowname, string attributes, variable clear=defaultValue)
	set the fields of the ELOG panel More...

static string	get_panel_message (string windowname)
	get the message field of the ELOG panel More...

static string	set_panel_message (string windowname, string message)
	set the message field of the ELOG panel More...

static string	get_panel_graphs (string windowname)
	get the names of the graphs selected for attachment More...

static string	set_panel_graphs (string windowname, string graphs)
	update selection of graphs for attachment More...

Variables
static const string	package_name = "pearl_elog"

static const string	package_path = "root:packages:pearl_elog:"

static const variable	kdfRoot = 0

static const variable	kdfVolatile = 1

static const variable	kdfPersistent = 2

static const variable	kdfTemplates = 3

static const string	elog_success_msg = "Message successfully transmitted"

static const string	elog_parse_id = "ID=%u"

static const variable	kAttachColSel = 0

static const variable	kAttachColTitle = 1

static const variable	kAttachColName = 2

Detailed Description

interface for writing ELOG entries with Igor graphs as attachment.

the functions in this module support the following ELOG features:

submit new entries and replies to existing entries.
text field, list box, and check box attributes.
attach any Igor graph to ELOG.
configurable logbook templates for logbooks that share the same configuration.
common server configurations available on the ELOG command line (hostname, port, SSL, username, password, sub-directory).
not specific to the configuration at PEARL. PEARL code is concentrated in the elog_init_pearl_templates() function.
the configuration of the ELOG server and logbooks as well as the most recently used attributes are persisted in the preference file.

usage:

the administrator of the ELOG server creates logbook templates according to the configuration of the logbooks. the templates are written in Igor code.
the user opens logbooks via the Open ELOG panel menu item. before first use, select a template and enter a name for the logbook. the new logbook is written to the preference file, and can afterwards be opened directly.
if the server requires a user name and password, click the login button.
edit the message, attributes and attachments as necessary, and submit to ELOG.
log out before saving the experiment to clear the password.

Attention

the user name and password are stored in the global data tree of an experiment. it is not possible to handle passwords safely in Igor. they can be read by anyone having access to an open Igor experiment or a saved experiment file (unless the password is reset before saving). therefore:

use a password for the ELOG server which is different from your other passwords.
clear the password (logout button in the panel) before saving an experiment.

elog command line

*  elog -h <hostname> [-p port] [-d subdir]
*                               Location where elogd is running
*      -l logbook               Name of logbook
*      -s                       Use SSL for communication
*      [-v]                     For verbose output
*      [-w password]            Write password defined on server
*      [-u username password]   User name and password
*      [-f <attachment>]        Up to 50 attachments
*      -a <attribute>=<value>   Up to 50 attributes
*      [-r <id>]                Reply to existing message
*      [-q]                     Quote original text on reply
*      [-e <id>]                Edit existing message
*      [-x]                     Suppress email notification
*      [-n 0|1|2]               Encoding: 0:ELcode,1:plain,2:HTML
*      -m <textfile>] | <text>
*

Author: matthias muntwiler, matth.nosp@m.ias..nosp@m.muntw.nosp@m.iler.nosp@m.@psi..nosp@m.ch

Copyright: 2013-17 Paul Scherrer Institut
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Definition in file pearl-elog.ipf.

Function Documentation

static variable AfterFileOpenHook	(	variable	refNum,
		string	file,
		string	pathName,
		string	type,
		string	creator,
		variable	kind
	)

static

initialize the package and reload preferences after an experiment is loaded.

Definition at line 143 of file pearl-elog.ipf.

static variable bp_attach ( WMButtonAction * ba )

static

Definition at line 1634 of file pearl-elog.ipf.

static variable bp_attach_allnone ( WMButtonAction * ba )

static

select/deselect all graph windows for attachment

Definition at line 1613 of file pearl-elog.ipf.

static variable bp_attach_top ( WMButtonAction * ba )

static

select top graph window for attachment

Definition at line 1597 of file pearl-elog.ipf.

static variable bp_attach_updown ( WMButtonAction * ba )

static

button procedure for the attachment up and down buttons

Definition at line 1518 of file pearl-elog.ipf.

static variable bp_clear ( WMButtonAction * ba )

static

Definition at line 1695 of file pearl-elog.ipf.

static variable bp_login ( WMButtonAction * ba )

static

Definition at line 1711 of file pearl-elog.ipf.

static variable bp_logout ( WMButtonAction * ba )

static

Definition at line 1729 of file pearl-elog.ipf.

static variable bp_save_graphs ( WMButtonAction * ba )

static

Definition at line 1667 of file pearl-elog.ipf.

static variable bp_submit ( WMButtonAction * ba )

static

button procedure for the Submit and Reply buttons

Definition at line 1550 of file pearl-elog.ipf.

static variable cleanup_temp_files ( )

static

delete temporary files created by the ELOG module.

this deletes all temporary graph files that are referenced by the volatile temp_graph_files list. temp_graph_files is a semicolon-delimited string. items are added by create_graph_file().

this function should be called before a new experiment is loaded or igor quits.

Definition at line 1115 of file pearl-elog.ipf.

static string create_cmd_file ( string cmd )

static

write the command line to a file.

the command script changes the working directory to the Temporary directory. it also deletes a previous elog.log file.

Note: somewhere the command line (even inside command files) is limited to 1024 bytes. for this reason all files should now be in the Temporary directory assigned by igor.

Definition at line 1059 of file pearl-elog.ipf.

static string create_graph_file	(	string	graphname,
		variable	fileindex
	)

static

save a graph to a temporary graphics file

the file is saved to the Temporary directory returned by igor's SpecialDirPath function. the file name contains a time stamp and the specified file index to make it unique. the function returns the name of the file (excluding path!)

the full path is added to the temp_graph_files global list. a hook function will delete the files listed there when igor quits.

Parameters

graphname	object name of the graph to save.
fileindex	incrememtal index of the file within one submission. the file name is made unique by a time stamp and this file index. submissions within the same second must have a unique file index.

Returns: (string) name of the created file. empty string if unsuccessful.

Version: 1.41 the return value has changed from full path to file name only due to the limited length of the command line (1024 bytes).

Definition at line 1023 of file pearl-elog.ipf.

static string create_message_file ( string message )

static

save the message to a temporary text file

the file is saved to the Temporary directory returned by igor's SpecialDirPath function under the file name "elog_temp_message.txt". the function returns the name of the file (excluding path!)

Note: percent characters (%) cannot be passed to elog. they are removed silently from the message.

Parameters

message text message to save to the file.

Returns: (string) name of the created file. empty string if unsuccessful.

Version: 1.41 the return value has changed from full path to file name only due to the limited length of the command line (1024 bytes).

Definition at line 982 of file pearl-elog.ipf.

variable elog_add_attachment	(	string	logbook,
		variable	id,
		string	graphs
	)

add one or more graphs to an existing ELOG entry

Parameters

logbook	name of the target logbook
id	identification number of the existing entry
graphs	names of graph windows to be added as attachments, semicolon separated

Warning: this will delete all existing attachments of the entry!

Definition at line 792 of file pearl-elog.ipf.

variable elog_config	(	string	elog_path = `defaultValue`,
		string	hostname = `defaultValue`,
		variable	port = `defaultValue`,
		string	subdir = `defaultValue`
	)

set global module configuration parameters

Definition at line 473 of file pearl-elog.ipf.

variable elog_create_entry	(	string	logbook,
		string	attributes,
		string	message,
		variable	encoding = `defaultValue`,
		string	graphs = `defaultValue`,
		variable	replyto = `defaultValue`
	)

create a new entry in ELOG

this is the main function to create a new entry in a logbook.

Parameters

logbook	name of the target logbook.
attributes	key=value list of attributes, semicolon separated.
message	free text part of the entry.
encoding	encoding of message, 0:ELcode, 1:plain (default), 2:HTML.
graphs	names of graph windows to be added as attachments, semicolon separated.
replyto	existing message ID (> 1) to follow up on. 0 or default: start new thread.

Returns

ID number of the new entry (> 0), or error code (< 0).

-1: failed to save temporary message file.
-2: invalid/missing command line.
-3: invalid/missing attributes.
-4: elog returned error

Definition at line 685 of file pearl-elog.ipf.

variable elog_create_logbook	(	string	name,
		string	template = `defaultValue`
	)

create a new logbook.

create a new empty logbook or duplicate from a template.

Parameters

name	name of the new logbook. if the logbook exists, the existing logbook folder is killed and replaced by a new one. this may fail if a window is still open.
template	name of the template. if empty string, a new empty logbook is created.

Definition at line 414 of file pearl-elog.ipf.

variable elog_init_pearl_templates ( )

setup PEARL template logbooks.

template logbooks for PEARL.

Remarks: this function is specific to the setup at PEARL.

Definition at line 262 of file pearl-elog.ipf.

variable elog_login	(	string	logbook,
		string	username,
		string	password
	)

set username and password for login to a logbook

the username and password are stored (in plain text) in global strings under the selected logbook folder. this is necessary for sending data to the ELOG server.

call elog_logout() to clear the password variables and to avoid unintended use of your credentials.

Warning: igor does not have a built-in mechanism to protect passwords. user names and passwords are stored in plain text in the data folder tree. as such they are saved to experiment files and preferences.

Parameters

logbook name of the target logbook.

Definition at line 513 of file pearl-elog.ipf.

variable elog_logout ( string logbook )

clear username and password of a logbook or all logbooks.

the username and password are stored (in plain text) in global strings under the selected logbook folder. this function resets the username and password strings.

Parameters

logbook name of the target logbook. if empty, the passwords of all logbooks are cleared.

Definition at line 533 of file pearl-elog.ipf.

static variable elog_panel_hook ( WMWinHookStruct * s )

static

Definition at line 1394 of file pearl-elog.ipf.

string elog_prompt_logbook ( )

prompt to open or create a logbook

Definition at line 1184 of file pearl-elog.ipf.

variable elog_prompt_login ( string logbook )

prompt the user for login to a logbook

Definition at line 1214 of file pearl-elog.ipf.

variable elog_validate_attributes	(	string	logbook,
		string	attributes
	)

validate attributes

Returns: 0 if all required attributes are present and enumerated items are correct. non-zero if a violation is detected.

Todo:: function currently not implemented, always returns 0

Definition at line 653 of file pearl-elog.ipf.

static string format_url ( string logbook )

static

format the URL for display to the user

Parameters

logbook name of the target logbook

Definition at line 902 of file pearl-elog.ipf.

static string get_default_panel_name ( )

static

Definition at line 1746 of file pearl-elog.ipf.

static dfr get_elog_df	(	string	name,
		variable	category
	)

static

get the package, logbook, or template datafolder.

Parameters

name	name of logbook or template, or empty string for respective parent folder.
category	parameter category: kdfRoot package root kdfVolatile volatile kdfPersistent persistent kdfTemplates template

Returns: data folder reference

Definition at line 170 of file pearl-elog.ipf.

static string get_log_path ( )

static

Definition at line 1095 of file pearl-elog.ipf.

static string get_panel_attributes ( string windowname )

static

get a list of attributes from the fields of the ELOG panel.

Parameters

windowname window name of the ELOG panel if empty, use default name "PearlElogPanel"

Returns: list of attributes to in the format "key1=value1;key2=value2".

Definition at line 1759 of file pearl-elog.ipf.

static string get_panel_graphs ( string windowname )

static

get the names of the graphs selected for attachment

Parameters

windowname panel window name

Returns: a semicolon-separated list, or the empty string if the selection is not valid.

Definition at line 1914 of file pearl-elog.ipf.

static string get_panel_message ( string windowname )

static

get the message field of the ELOG panel

Parameters

windowname window name of the ELOG panel if empty, use default name "PearlElogPanel"

Returns: message text

Definition at line 1868 of file pearl-elog.ipf.

static string get_timestamp ( string sep )

static

Definition at line 958 of file pearl-elog.ipf.

static variable IgorBeforeNewHook ( string igorApplicationNameStr )

static

save preferences and recent values before Igor opens a new experiment.

Definition at line 127 of file pearl-elog.ipf.

static variable IgorQuitHook ( string igorApplicationNameStr )

static

save preferences and recent values before Igor quits.

Definition at line 135 of file pearl-elog.ipf.

static variable init_package ( variable clean = defaultValue )

static

initialize the package data folder.

the data folder is initialized with a default, local configuration without any logbooks. the server configuration should be set in the preferences.

Parameters

clean

decides what to do if the package configuration exists.

0 (default) keep existing configuration.
1 overwrite existing configuration.

Definition at line 217 of file pearl-elog.ipf.

static variable init_volatile_vars ( )

static

initialize volatile variables.

create and initialize all volatile variables for the configured notebooks. values of existing variables are not changed.

this function must be called after new logbooks have been configured, specifically by elog_create_logbook() and load_prefs().

Definition at line 340 of file pearl-elog.ipf.

static string list_logbooks ( variable templates = defaultValue )

static

get a list of configured logbooks or templates.

this is list of data folder names under persistent:logbooks (or persistent:templates). the function does not check whether the folders contain valid data.

Parameters

templates select whether logbooks (0, default) or templates (1) are returned.

Returns: semicolon-separated list of logbooks

Definition at line 618 of file pearl-elog.ipf.

static variable load_prefs ( )

static

load persistent package data from the preferences file.

the preferences file is an Igor packed experiment file in a special preferences folder

Definition at line 584 of file pearl-elog.ipf.

static variable move_attach_item	(	string	logbook,
		variable	item,
		variable	distance
	)

static

move an attachment item in the list of attachments

Definition at line 1494 of file pearl-elog.ipf.

static variable parse_result ( )

static

parse the result file from an elog invokation.

Returns: the ID of the generated message, or a value <= 0 if an error occurred.

Definition at line 1141 of file pearl-elog.ipf.

variable pearl_elog ( string logbook )

main function to initialize ELOG and to open an ELOG panel.

this function takes care of all necessary initialization, configuration, and preferences. if a panel exists, it will be moved to the front.

Parameters

logbook name of the logbook if empty, the user is prompted to select or create a logbook by elog_prompt_logbook().

Definition at line 97 of file pearl-elog.ipf.

string PearlElogPanel ( string logbook )

open a new panel for submitting data to ELOG.

this function creates only the panel but not the necessary data folders. call init_package() and load_prefs() once before creating panels.

Parameters

logbook name of the target logbook

Definition at line 1241 of file pearl-elog.ipf.

static string prepare_command_line ( string logbook )

static

format the ELOG command and essential address arguments.

the following arguments are included (from global variables) if applicable: host name, port, SSL, sub-dir, username, password the result string does not include leading or trailing space

Parameters

logbook name of the target logbook

Definition at line 853 of file pearl-elog.ipf.

static string prepare_graph_attachments ( string graphs )

static

prepare screenshots of graph windows for attachments

prepares the attachment files from Igor graph windows and returns the arguments to the elog command to attach the files. file names are returned without path. the result string does not include leading or trailing space.

Parameters

graphs names of graph windows to be added as attachments, semicolon separated

Definition at line 939 of file pearl-elog.ipf.

static variable save_prefs ( )

static

save persistent package data to the preferences file.

saves everything under the persistent folder of the package.

Definition at line 564 of file pearl-elog.ipf.

static string set_panel_attributes	(	string	windowname,
		string	attributes,
		variable	clear = `defaultValue`
	)

static

set the fields of the ELOG panel

Parameters

windowname	window name of the ELOG panel if empty, use default name "PearlElogPanel"
attributes	list of attributes to set (format "key1=value1;key2=value2")
clear	what to do if a key is missing in attributes? 0 (default) leave the field unchanged 1 clear the field

Definition at line 1806 of file pearl-elog.ipf.

static string set_panel_graphs	(	string	windowname,
		string	graphs
	)

static

update selection of graphs for attachment

Parameters

windowname	panel window name. looks for default panel if empty.
graphs	semicolon-separated list of names of graph windows to select for attachment.

Definition at line 1954 of file pearl-elog.ipf.

static string set_panel_message	(	string	windowname,
		string	message
	)

static

set the message field of the ELOG panel

Parameters

windowname	window name of the ELOG panel if empty, use default name "PearlElogPanel"
message	message text that can be passed to the `Notebook` operation.

Returns: original message (unchanged)

Definition at line 1894 of file pearl-elog.ipf.

static variable update_attach_items ( string logbook )

static

update the list of attachments

Definition at line 1433 of file pearl-elog.ipf.

Variable Documentation

const string elog_parse_id = "ID=%u"

static

Definition at line 1134 of file pearl-elog.ipf.

const string elog_success_msg = "Message successfully transmitted"

static

Definition at line 1133 of file pearl-elog.ipf.

const variable kAttachColName = 2

static

Definition at line 1430 of file pearl-elog.ipf.

const variable kAttachColSel = 0

static

Definition at line 1428 of file pearl-elog.ipf.

const variable kAttachColTitle = 1

static

Definition at line 1429 of file pearl-elog.ipf.

const variable kdfPersistent = 2

static

Definition at line 155 of file pearl-elog.ipf.

const variable kdfRoot = 0

static

Definition at line 153 of file pearl-elog.ipf.

const variable kdfTemplates = 3

static

Definition at line 156 of file pearl-elog.ipf.

const variable kdfVolatile = 1

static

Definition at line 154 of file pearl-elog.ipf.

const string package_name = "pearl_elog"

static

Definition at line 85 of file pearl-elog.ipf.

const string package_path = "root:packages:pearl_elog:"

static

Definition at line 86 of file pearl-elog.ipf.

Namespaces

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation