SOLD OUT カスタマイズに利用できる関数の説明です。
呼び出し時の関数名と引数を示します。
引数表記に関しては、以下の表記ルールを用いています。
関数が返す値の意味を示します。
特に表記がない場合は package main
に属しています。
package item
や package event
からの呼び出し時には
明示的に main::function()
として呼び出してください。
また、package main
に属する関数はいつでも(どの処理からも)呼び出せると思いますが、
package item
や package event
に属する関数は、利用できる場面が限定されます。
利用可能な場面の詳細はそれぞれの関数説明をご覧下さい。
Lock()
なし
データ更新用に排他ロックをかけます。別のプロセスのLockをブロックします。
各種データを書き換える前にはまずロックし、その後必要なデータを読み書きしてください。 ロックせずにデータを書き換えた場合は、同時アクセス等が原因でデータが破損する可能性があります。
データ書き換え後はすみやかにUnLockにてロックを解除してください。
Lock呼び出しは入れ子にすることが出来ますが、実際にロックするのは最初だけです。
ロックに失敗した場合は致命的エラーとして処理を中断し、エラーがあったことをログに記録します。
Lock(); # ロック DataRead(); DataWrite(); DataCommitOrAbort(); UnLock();
UnLock()
なし
ロック(Lock)を解除します。
Lock呼び出しが入れ子になっている場合は、最後のUnLockでロック解除されます。
ロック解除に失敗した場合は致命的エラーとして処理を中断し、エラーがあったことをログに記録します。
ロックされている間は、他の店舗は一切作業が出来ません。 ロックは必要最小限かつロック解除はすみやかに行ってください。
Lock(); DataRead(); DataWrite(); DataCommitOrAbort(); UnLock(); # ロック解除
CheckLockStatus()
なし
現在Lockされているかどうかを確認します。 ファイル更新を行う前に念のためチェックしたい場合に利用できます。
Lockされていなければ致命的エラーとして処理を中断し、エラーがあったことをログに記録します。
CheckLockStatus(); # 事前にロックされているかチェック DataRead(); DataWrite(); DataCommitOrAbort(); UnLock();
DataRead()
なし
店舗や街のデータを読み込みます。 読み込んだデータは変更ができます。 商品データ記述文法 や 各種データ表内の $DT @DT 等を参考にしてください。
Lock(); DataRead(); # データ読み込み DataWrite(); DataCommitOrAbort(); UnLock();
DataWrite()
なし
DataReadで読み込んだデータを書き込みます。 事前にLockする必要があります。
書き込みに失敗した場合は致命的エラーとして処理を中断し、エラーがあったことをログに記録します。
なお、書き込みに成功したとしても、DataCommitOrAbortを行わなければ反映されません。 DataWriteを反映させるためには必ずDataCommitOrAbortを行ってください。
また、soldout/_config.cgi
の設定に従い、データのバックアップ作業を行います。
こちらはDataCommitOrAbort実行の有無に関係なく行われます。
Lock(); DataRead(); DataWrite(); # 書き込み&バックアップ DataCommitOrAbort(); UnLock();
WriteLog(重要度,対象店舗ID,送信元店舗ID,'メッセージ',Lockの有無)
なし
最近の出来事にメッセージを記録します。
※item::WriteLog event::WriteLog とは引数が違います。
WriteLog(0,0,0,'一般メッセージ',1); WriteLog(1,0,0,'重要メッセージ',1); WriteLog(2,0,0,'情報メッセージ',1); WriteLog(0,0,123,'店舗ID123用(秘)メッセージ',1);戻り値
なし
{ my($mode,$from,$to,$msg,$nolock)=@_;
DataFilesBackup()
なし
soldout/_config.cgi
の設定に従い、データのバックアップを行います。
Lock(); DataFilesBackup(); UnLock(); # ロックしないとバックアップ中にファイルが変更されて不整合が起こる可能性があります。
DataCommitOrAbort(['abort'])
なし
引数がない場合は、
soldout/data/temp
への書き込みデータファイルをsoldout/data
へ上書き反映させます。
複数のファイルを同時に更新する必要がある場合に利用してください。
引数が 'abort' の場合は、soldout/data/temp
への書き込みを全て破棄します。
note:複数のファイルを同時に更新する際 perl の処理が何らかの原因で中断されると、 片方は更新されたがもう片方は更新されなかった等、ファイル間のデータに不整合が起きる可能性があります。 それを出来る限り防ぐための関数です。 この関数を利用すると、「全ファイル更新完了」か「全ファイル更新破棄」となります。
Lock(); DataRead(); DataWrite(); DataCommitOrAbort(); # 書き込み反映 UnLock();
OpenAndCheck('書き込み用ファイル名')
なし(書き込み用ファイルハンドルOUTがオープンされます)
新規書き込み用ファイルを念入りにオープンし、ファイルハンドルOUT
を作成します。
使用済みのOUT
は手動で閉じてください。(close OUT
)
my $out_file=GetPath('test'); # data/test.cgi OpenAndCheck($out_file); print OUT "test\n"; close OUT;
RenameAndCheck('リネーム前のファイル名','リネーム後のファイル名')
なし
ファイルを念入りにリネームします。
失敗した場合は致命的エラーとして処理を中断し、エラーがあったことをログに記録します。
my $old_file=GetPath('test-old'); # data/test-old.cgi my $new_file=GetPath('test-new'); # data/test-new.cgi RenameAndCheck($old_file,$new_file);
GetTownData('キーワード')
キーワードに対応するデータ
サイト固有のデータとして記録されているキーワードのデータを取得します。
データを記録するには SetTownData を使用します。
my $sum_tax=GetTownData('sum_tax'); $sum_tax+=$today_tax; SetTownData('sum_tax',$sum_tax); # $today_tax を 'sum_tax' という街データとして累計保存する
SetTownData('キーワード','データ')
セットされたエスケープ済みデータ(確認用)
サイト固有のデータを記録します。キーワードとデータを指定してください。
記録されたデータは GetTownData で取得できます。
my $sum_tax=GetTownData('sum_tax'); $sum_tax+=$today_tax; SetTownData('sum_tax',$sum_tax); # $today_tax を 'sum_tax' という街データとして累計保存する
OutError('エラーメッセージ')
なし(exitします)
エラーメッセージを表示し、処理を中断します。 Lockしていた場合は自動的に解除され、 DataCommitOrAbortしていない書き込みデータは破棄されます。
OutError('エラーのため終了します');
WriteErrorLog('エラーメッセージ','ログ種別コード(ファイル名ベース部分)')
なし
エラーメッセージを、指定されたログ種別コードのログファイルへ追記します。
WriteErrorLog('エラー','error'); WriteErrorLog('移転エラー','movetown');
GetPage(現在のページ番号,1ページのレコード数,レコード総数)
(現在のページ番号,開始レコード番号,終了レコード番号,次ページの番号,前ページの番号,ページ総数)
1 ページに入りきれないような配列(レコード)のために、ページ計算を行います。
ページ番号は 0 から始まります。 1 ページ目は 0 、 2 ページ目は 1 、 3 ページ目は 2 、という対応になります。
引数詳細
戻り値詳細
# $now_page : 現在のページ番号 # $LIST_PAGE_ROWS : 1ページの行数 # @MESSAGE : メッセージ配列 # $disp : 出力HTML # $type : 追加パラメータ(type) my($page,$pagestart,$pageend,$pagenext,$pageprev,$pagemax)=GetPage($now_page,$LIST_PAGE_ROWS,scalar(@MESSAGE)); $disp.=GetPageControl($pageprev,$pagenext,"&type=$type","pg",$pagemax,$page)."\n"; $disp.="現在のページ ".($page+1)."\n"; $disp.="最後のページ ".($pagemax+1)."\n"; $disp.="次のページ ".($pagenext+1)."\n"; $disp.="前のページ ".($pageprev+1)."\n"; foreach my $line (@MESSAGE[$pagestart..$page_end]) { $disp.=$line."\n"; }
GetPageControl(前ページの番号,次ページの番号,'追加パラメータ','ページ番号のパラメータ名',ページ総数,現在のページ番号)
'ページコントロール用HTML'
GetPage等で得られた情報を元に、ページコントロール用 HTML を生成します。
引数詳細
# $now_page : 現在のページ番号 # $LIST_PAGE_ROWS : 1ページの行数 # @MESSAGE : メッセージ配列 # $disp : 出力HTML # $type : 追加パラメータ(type) my($page,$pagestart,$pageend,$pagenext,$pageprev,$pagemax)=GetPage($now_page,$LIST_PAGE_ROWS,scalar(@MESSAGE)); $disp.=GetPageControl($pageprev,$pagenext,"&type=$type","pg",$pagemax,$page)."\n"; $disp.="現在のページ ".($page+1)."\n"; $disp.="最後のページ ".($pagemax+1)."\n"; $disp.="次のページ ".($pagenext+1)."\n"; $disp.="前のページ ".($pageprev+1)."\n"; foreach my $line (@MESSAGE[$pagestart..$page_end]) { $disp.=$line."\n"; }
GetTagImgGuild('ギルドコード'[,'noimage'[,'movetown']])
'ギルドマーク画像用HTMLもしくはギルド名'
ギルドコードからギルドマーク画像の HTML(<img>)やギルド名を取得します。 引数により、取得できる文字列が変わります。
存在しないギルドコードを指定した場合は「解散したギルド」というギルド名に置き換えられます。
引数詳細
my $guild_html=GetTagImgGuild('mutoysblue'); # mutoysblue というギルドコードのギルドのHTML my $guild_name=GetTagImgGuild('mutoysblue','noimage'); # mutoysblue というギルドコードのギルドの名称
GetStockTime(持ち時間データ($DT->{time}相当))
持ち時間秒数
持ち時間を表す時刻データ(最後に作業を完了した時刻)から、実際の持ち時間秒数を取得します。
持ち時間が設定(soldout/_config.cgi
)された最大時間を超えていれば、最大時間に補正されます。
my $stock_time=GetStockTime($DT->{time}); # 持ち時間取得 my $stock_time_string=GetTime2HMS($stock_time);
GetUserDataEx($DT,'キーワード')
キーワードに対応するユーザデータ
$DT->{user}のデータを安全に取得します。
$DT->{user}を直接操作する場合と違い、特殊文字であるカンマ(,)、コロン(:)、改行(\n)等も取得できますが、 そのためにはあらかじめSetUserDataExでデータを設定する必要があります。
つまり、同じキーワードに対しては、$DT->{user}を直接操作するか、 GetUserDataExとSetUserDataExを経由させるかで、統一する必要があります。
カスタマイズ互換性維持のために $DT->{user} の直接操作も可能ですが、 今後は GetUserDataExとSetUserDataEx の利用をお勧めします。
なお、'_so_' から始まるキーワードはシステム予約としていますので、使用しないでください。
my $in_time=GetUserDataEx($DT,'town_in'); # $in_time に $DT->{user}{town_in} を取得する。
SetUserDataEx($DT,'キーワード','データ')
セットされたエスケープ済みデータ(確認用)
$DT->{user}のデータを安全に記録します。キーワードとデータを指定してください。
記録されたデータは GetUserDataEx で取得できます。
なお、'_so_' から始まるキーワードはシステム予約としていますので、使用しないでください。
SetUserDataEx($DT,'town_in',time()); # 現時刻を $DT->{user}{town_in} に記録する。
EditMoney($DT,増減額)
なし
$DT の資金(money)を増減します。
最大金額を超えたり\0 未満になった場合は補正されます。
EditMoney($DT,-1234); # $DT->{money}から\1234引きます。
EditTime($DT,増減持ち時間)
なし
$DT の持ち時間を増減します。
EditTime($DT,12*60*60); # 持ち時間を12時間(12*60*60秒)増やします。
GetID2UserName(ユーザID)
('店舗名','ユーザ名')
ユーザ ID($DT->{id})から店舗名とユーザ名を取得します。
存在しないユーザ ID の場合は('閉店済','')を返します。
my($shopname,$username)=GetID2UserName($DT->{id});
GetMenuTag('ファイル名(ベース部分)','表示文字列'[,'付加するパラメータ'])
'アンカー<a>...</a>文字列'
メニューとなるアンカー <a href="....">....</a> を取得します。 すでにログインされている場合は、ログイン情報(ユーザ名やセッション情報など)も付加します。
引数詳細
my $menu_1=GetMenuTag('test','テストページ'); test.cgi へのリンクHTML my $menu_2=GetMenuTag('test','テストページ','&type=1'); test.cgi へのリンクHTML(パラメータ付)
RequireFile('読み込むファイル名')
なし
soldout/custom
、soldout/inc
の順に指定されたファイルを探し、読み込みます。
RequireFile('custom.cgi'); # custom/custom.cgi、inc/custom.cgi の順に検索し、見つかった方を読み込む。
GetPath(['ディレクトリ',...,]'ファイル名(ベース部分)')
'ファイルパス'
ディレクトリとファイル名(ベース部分)を元に、規定の拡張子が付いたファイルパスを取得します。
ディレクトリを省略し、ファイル名のみ指定された場合は、
ディレクトリにsoldout/data
が指定されたものとみなされます。
GetPath('test'); # data/test.cgi GetPath('test_dir','test'); # test_dir/test.cgi GetPath('test_dir','test_dir2','test'); # test_dir/test_dir2/test.cgi
CheckCount(入力値1,入力値2,最小値,最大値)
補正された値
主にユーザの入力値補正に使います。デフォルト値と最小値、最大値の補正を行います。また、小数を切り捨てます。
引数詳細
# $input_count : ユーザ入力されたカウント $input_count=CheckCount(100,$input_count,50,150); # 補正後の $input_count # 入力値が0か空文字の場合 : 100 # 入力値が数値ではない場合: 100 # 入力値が50未満の場合 : 50 # 入力値が150を超える場合 : 150 # 入力値が小数を含む場合 : 小数切り捨て # それ以外の場合 : 補正しません
CutStr('SJIS文字列',最大文字列長)
'補正された文字列'
文字列を指定された長さ(byte)に切り詰めます。
日本語コードは SHIFT JIS のみ対応しています。 切り詰める境界が SHIFT JIS の第 1 バイトと第 2 バイトの間になった場合は、 第 1 バイトを含めて切り捨てます。
require 'jcode.pl'; # jcode.pl を利用して jcode::sjis(\$string); # $string を SHIFT JIS に変換 $string=CutStr($string,40); # 半角40文字(全角20文字)以内に切り詰めます。
EscapeHTML('HTML文字列')
'エスケープされた文字列'
HTML で特別な意味を持つ文字 & < > " を & < > " にエスケープします。
ユーザ入力された文字列を表示する場合は、危険なタグを無効にするためにこの関数を通してから表示するといいでしょう。
my $escape=EscapeHTML('<img src="analyze.cgi?">'); # $escape は '<img src="analyze.cgi">' になります。
GetFileTime('ファイル名(ベース部分)')
時刻秒数(GMT)
soldout/data
に存在するファイルの最終更新時刻を取得します。
my $file_time=GetFileTime('test'); # data/test.cgi の最終更新時刻を取得 my $file_time_string_1=GetTime2FormatTime($file_time); my $file_time_string_2=GetTime2FormatTime($file_time,'full');
GetTime2HMS(時間秒数)
'時間を表す文字列'
秒数から「?日」「?時間」「?時間?分」「?分」「?秒」といった形式を取得します。
my $stock_time=GetStockTime($DT->{time}); my $stock_time_string=GetTime2HMS($stock_time); # 持ち時間秒数を読みやすい形式で取得
GetTime2FormatTime(時刻秒数(GMT)[,'full'])
'時刻を表す文字列'
時刻秒数から「 01/23 04:56 」「 01/23 」「 04:56 」といった形式を取得します。
引数 'full' が指定された場合は、常に「 01/23 04:56 」といった「日付 時刻」形式になります。
引数 'full' が省略された場合は、「本日もしくは 12 時間以内」では「 04:56 」という時刻形式となり、 それ以外の場合は「 01/23 」といった日付形式になります。
my $file_time=GetFileTime('test'); my $file_time_string_1=GetTime2FormatTime($file_time); # data/test.cgi の最終更新時刻を読める形式で取得 (??/?? or ??:??) my $file_time_string_2=GetTime2FormatTime($file_time,'full');# data/test.cgi の最終更新時刻を読める形式で取得 (??/?? ??:??)
GetTagA('表示文字列','リンク先URL'[,'リンク無し'[,'target属性']])
'アンカータグ文字列'
リンク用タグ(アンカータグ<a>)を取得します。
my $link_1=GetTagA('テストリンク','test.html'); # test.html へのリンクHTML my $link_2=GetTagA('テストリンク','test.html','nolonk'); # テストリンク という文字列(非HTML) my $link_3=GetTagA('テストリンク','test.html','','_blank'); # test.html へのリンクHTML(target="_blank"付) my $link_4=GetTagA('テストリンク','test.html',$login ? '' : 'nolonk'); # $login が真の場合はリンク/偽の場合は非リンク
item::WriteLog(重要度,対象店舗ID,'メッセージ')
event::WriteLog(重要度,対象店舗ID,'メッセージ')
なし
最近の出来事にメッセージを記録します。
※WriteLog とは引数が違います。注意してください。 なお、本関数は内部で WriteLog を呼び出しています。
WriteLog(0,0,'一般メッセージ'); WriteLog(1,0,'重要メッセージ'); WriteLog(2,0,'情報メッセージ'); WriteLog(0,123,'店舗ID123用(秘)メッセージ');
item::WriteLog 利用可能範囲
event::WriteLog 利用可能範囲
item::DebugLog('メッセージ')
event::DebugLog('メッセージ')
なし
soldout/_config.cgi
の設定により、開発時のデバッグ用ログ出力を行います。
出力されたログは管理メニューから参照できます。
DebugLog('デバッグログ');
item::DebugLog 利用可能範囲
event::DebugLog 利用可能範囲
item::UseItem(商品番号,消費数[,'メッセージ'])
なし
パッケージ変数 $item::DT の店舗に対して商品番号の商品を消費させます。 残りが 0 以下になった場合は 0 に補正されます。
メッセージがあると、その旨通知されます。メッセージは省略可能です。
UseItem(12,34); UseItem(12,34,'No.12を消費しました');
利用可能範囲
item::UseItemSub(商品番号,消費数,対象店舗データ($DT))
実際の消費数
item::UseItemの下請け関数ですが、汎用的に利用できます。
対象店舗データの商品在庫から商品番号の商品を消費させます。 残りが 0 以下になった場合は 0 に補正されます。
UseItemSub(12,34,$DT);
利用可能範囲
item::AddItem(商品番号,取得数[,'メッセージ'])
なし
パッケージ変数 $item::DT の店舗に対して商品番号の商品を取得させます。 所持最大数を超えた場合は最大数に補正されます。
メッセージがあると、その旨通知されます。メッセージは省略可能です。
AddItem(12,34); AddItem(12,34,'No.12を取得しました');
利用可能範囲
item::AddItemSub(商品番号,取得数,対象店舗データ($DT))
実際の取得数
item::AddItemの下請け関数ですが、汎用的に利用できます。
対象店舗データの商品在庫から商品番号の商品を取得させます。 所持最大数を超えた場合は最大数に補正されます。
AddItemSub(12,34,$DT);
利用可能範囲